Programming

Here's everything related to documentation about the patch. This page is meant for ASM developers.

RAM

The patch reserves 5 consecutive bytes of RAM at $7E18C5 and XXX consecutive bytes at $7E2000 ($78C5 and $404000 respectively on SA-1 Pack enhanced ROMs), as this patch no longer makes use of GFX32 to obtain player graphics.

Graphics information

The graphics can be swapped on real time with no real visible lag, as it doesn't have to decompress graphics or rebuild data. You just need to bypass the original logic and set the ID of the player graphics you want to display on screen. Do note that it doesn't swap the entire set of graphics (gfx, palette, extra tile), it just changes the pointer of the graphics.

Displacements of OAM tiles that are used for the player can be changed at your discretion, by either using ROM tables or RAM tables. By default the system uses ROM tables, but RAM tables might be useful in such cases where you have a very dynamic player with various moving parts in its kit. The usage of RAM tables requires you to manipulate the data, as this system doesn't offer anything to help you with that task besides letting you use RAM.

Define	Size	Description
!player_graphics_index	8-bit	Contains the slot ID for the current player graphics displayed on the screen.
!player_graphics_pointer	24-bit	Holds the pointer to the current player graphics.
!player_graphics_bypass	8-bit	Flag that lets you bypass the original logic for selecting the player GFX. The system will use whatever value you write to !player_graphics_index to determine which player graphics it will display. Any non-zero value will bypass the original logic.
!player_graphics_disp_settings	8-bit	Controls how the system will deal with player OAM tile displacements. Format: Bit 0: If set, the system will make use of ROM tables for OAM displacements. If not set, the system will use the data in !player_graphics_x_disp and !player_graphics_y_disp for OAM displacements.
!player_graphics_x_disp	256 bytes	Reserved area to hold the data for OAM displacements in the X axis.
!player_graphics_y_disp	256 bytes	Reserved area to hold the data for OAM displacements in the Y axis.

Palette information

Palettes in this system can be instantly changed just like graphics; just set the bypass flag and the ID in the corresponding RAM addresses and you're good to go. Do note that it doesn't swap the entire set of graphics (gfx, palette, extra tile), it just changes the pointer of the palette data.

Define	Size	Description
!player_palette_index	8-bit	Contains the slot ID for the current player palette displayed on the screen.
!player_palette_pointer	24-bit	Holds the pointer to the current player palette.
!player_palette_bypass	8-bit	Flag that lets you bypass the original logic for selecting the player palette. The system will use whatever value you write to !player_palettes_index to determine which player palette it will display. Any non-zero value will bypass the original logic.

Extra tile information

The original cape tile can be used outside the player with a cape ($7E0019 == $02) and repurposed for anything you'd like (as long you provide the logic for it). This feature has been seen in the powerups patch for a long time in several powerups (small cloud following the player in Cloud Mario, raccoon tail for the SMB3 powerups, propeller for the propeller suit, etc) if you'd like an example of how powerful this feature is.

Setting up the feature requires putting its code under the global or powerup animation codes (player_graphics/global_animations.asm and player_graphics/powerup_animations.asm respectively) depending on your needs. To make it display you have to do the following:

• Set the least significant bit (LSB) and keep clear the most significant bit (MSB) of !player_extra_tile_settings, as the MSB forces the system to draw the extra tile with the cape image logic regardless of the status of the LSB.
• Input the X and Y offsets for the tile, they're relative to the player position and 16-bit.
• Write to !player_extra_tile_frame the frame that's meant to be displayed on the screen.
• (Optional) Specify a different OAM index for the tile if you want via !player_extra_tile_oam and activating this feature by setting bit 1 from !player_extra_tile_settings

Define	Size	Description
!player_extra_tile_settings	8-bit	Settings for the extra tile. Format: Bit 0: If set, the extra tile will be shown. If not set, it will not draw anything on screen. Bit 1: If set, the OAM tile will be written to $0300 + !player_extra_tile_oam If not set, the OAM tile will be written to $03XX Bli 7: If set, the extra tile will use the same logic for drawing it on screen as the cape, minus the graphics. If not set, the system will use LSB to decide what to do.
!player_extra_tile_offset_x	16-bit	Displacement on the X axis for the extra tile. Relative to the player position in the current frame.
!player_extra_tile_offset_y	16-bit	Displacement on the Y axis for the extra tile. Relative to the player position in the current frame.
!player_extra_tile_frame	8-bit	Index for the tile shown on screen.
!player_extra_tile_oam	8-bit	OAM index for the extra tile. The final OAM address would be $0300 + this RAM value

Programming global and per powerup animations

The patch has two methods of adding extra animations to your players: globally and per powerup. Global animations have priority over the vanilla animations so you can use these to override them with a more logically complex animation and powerup animations have priority over global ones, for cases where you want to override certain vanilla or global animations with logic that only applies to that powerup.

You can find the global animations file in player_graphics/global_animations.asm and the powerup animations file in player_graphics/powerup_animations.asm.

To have your animation be properly displayed you should write to !player_pose_num the desired tilemap value to draw.