From 6b72b7d120720086709df2c4aa9f4ab50b6fad8f Mon Sep 17 00:00:00 2001 From: Miquel Sabaté Solà Date: Wed, 18 Mar 2026 15:54:07 +0100 Subject: Expand documentation on items.s MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The format of buffers are somewhat stable now, so we can expand the documentation to write down what I've finally settled on. Signed-off-by: Miquel Sabaté Solà --- src/items.s | 39 +++++++++++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 10 deletions(-) diff --git a/src/items.s b/src/items.s index 447b874..4d87b00 100644 --- a/src/items.s +++ b/src/items.s @@ -17,7 +17,7 @@ zp_player_screen_x = $45 ; asan:ignore PLAYER_WAIST = $0C - ;; The tile coordinates are also cached during the update() + ;; The player's tile coordinates are also cached during the update() ;; function. Reserve them into their own memory regions to avoid surprises ;; by using the 'Globals::zp_arg0' and 'Globals::zp_arg1' variables which ;; are also being used by the background check. @@ -33,6 +33,10 @@ ;; The capacity of the items pool in bytes. POOL_CAPACITY_BYTES = POOL_CAPACITY * SIZEOF_POOL_ITEM + ;; Base address for the pool of items used on this game. The pool has + ;; '#Items::POOL_CAPACITY' capacity of item objects where each one is + ;; 'Items::SIZEOF_POOL_ITEM' bytes long: + ;; ;; 1. State: $FF for invalid, otherwise: ;; |PFD- CKKK|; where: ;; | @@ -49,23 +53,38 @@ ;; Preserves the index on 'zp_pool_base' in Items::update(). zp_pool_index = $C9 - ;; TODO: stabilize and document. + ;; Buffer which caches extra data for each item which is useful for + ;; collision checks, or rendering the item itself. It follows the same + ;; format as 'Items::zp_pool_base', with the same order. Thus, with the same + ;; 'Items::zp_pool_index', you can index the same enemy on both buffers. For + ;; each buffer we have the following: + ;; + ;; | tile Y | tile X | palette / tile ID | + ;; | + ;; |- tile Y/X: tile coordinates for the item. + ;; |- palette: palette identifier to be used for the item. + ;; |- tile ID: the tile ID to be used for the item as its top-left sprite. ;; - ;; Y tile | X tile | palette/tile ID + ;; NOTE: palette and tile ID live on the same byte. 'palette' is on the high + ;; nibble, and tile ID on the low nibble. zp_current_tiles = $E7 ; asan:reserve POOL_CAPACITY_BYTES - ;; - ;; TODO: stabilize and document. + ;; Bitmap which holds different boolean values for the state of items in + ;; general. ;; ;; |GNS- --FF| ;; | - ;; |- G: the player is grabbing an item - ;; |- N: a fuel tank is needed. - ;; |- S: there is a fuel tank on screen. (TODO: needed?) - ;; |- F: number of falling items. + ;; |- G: the player is Grabbing an item + ;; |- N: a fuel tank is Needed. + ;; |- S: there is a fuel tank on Screen. + ;; |- F: number of Falling items. zp_state = $CA - ;; Number of shuttle parts (or fuel tanks) that have been collected so far. + ;; Number of shuttle parts (or fuel tanks) that have been collected so + ;; far. Note that parts which are now part of the background are also + ;; computed on this variable. Hence, even the low part of the shuttle which + ;; is always in the background is computed as a collected item. This makes + ;; things simpler to deal with. zp_collected = $CB ;; Coordinate where the dropping of items takes place. -- cgit v1.2.3