From 76149f0a69cda2921a518f72a2d93c16cccc7b3a Mon Sep 17 00:00:00 2001 From: Chris Mounce Date: Wed, 18 Mar 2026 13:37:07 -0700 Subject: [PATCH] Add documentation for Stat struct --- src/world.rs | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/src/world.rs b/src/world.rs index 53349e7..c5a21b8 100644 --- a/src/world.rs +++ b/src/world.rs @@ -232,20 +232,92 @@ impl Debug for Board { } /// A status element on a ZZT board. +/// +/// Stats provide additional data for specific tiles on the board. The majority of tiles will be +/// static, such as most of the board terrain (walls, water, empties, etc). But many things that +/// move, or any tile that needs state or code, will have an associated stat. +/// +/// A stat's x/y coordinates are what link them to their associated tiles. Typically this is a 1:1 +/// relationship: if there is an object tile at (12, 34), the board's stat list will usually have +/// exactly one entry that points to (12, 34). However, there are advanced use cases for having +/// multiple stats (or no stats!) in specific situations. So zztff does not enforce a 1:1 +/// relationship---that is the responsibility of editing software that wants to be user friendly. +/// +/// ZZT has a wide variety of tile types, called elements. The precise meanings of some of the +/// fields (particularly `p1`, `p2`, and `p3`) will vary depending on which tile the stat is pointed +/// at. You may want to consult a reference source, such as [the wiki articles on +/// elements](https://wiki.zzt.org/wiki/Element), for more info. #[derive(Debug, Clone)] pub struct Stat { + /// X coordinate of the stat's tile (1-based). pub x: u8, + /// Y coordinate of the stat's tile (1-based). pub y: u8, + /// Horizontal step delta. + /// + /// This is usually -1, 0, or 1. Paired with `y_step`, the step deltas are used to encode + /// direction or movement. For example, for transporters, this encodes which direction the + /// transporter is facing, whereas for pushers, it encodes the direction of movement. + /// + /// Step values of (0, 0) or the four cardinal directions are the most common. Other step values + /// are possible and are useful for advanced techniques, but care must be taken to ensure that + /// they are safe; ZZT's bounds checking code assumes step distances will never exceed 1, so + /// steps larger than that may go off-board and cause memory corruption. pub x_step: i16, + /// Vertical step delta. pub y_step: i16, + /// How often this stat is updated, in game ticks. + /// + /// Roughly speaking, stats update every 1/cycle game ticks. A cycle 1 object will run its code + /// on every tick, a cycle 2 object runs every other tick, etc. pub cycle: i16, + /// Element-specific parameter 1. pub p1: u8, + /// Element-specific parameter 2. pub p2: u8, + /// Element-specific parameter 3. pub p3: u8, + /// Index of the following stat in a centipede chain, or -1 if none. + /// + /// Leader and follower do not need to be explicitly set if you are creating a world from + /// scratch; if there are no existing links, ZZT will automatically link adjacent segments into + /// a chain when the board first loads. These pointers are used mainly for preserving the state + /// of saved games---but a world author could still use them if they needed a specific centipede + /// layout for some reason. pub follower: i16, + /// Index of the leading stat in a centipede chain, or -1 if none. pub leader: i16, + /// The tile that is underneath this stat. + /// + /// This is often an empty tile, but it may be something else if the stat was placed on top of + /// another terrain element (such as a fake wall/floor). ZZT uses this field to fill in the gap + /// if this stat ever moves; tracking the `under` type allows stats to move over terrain without + /// erasing it. + /// + /// Note that this field only holds a tile, i.e., not a stat. In general, ZZT assumes that a + /// given coordinate can only be occupied by one stat at a time. For example, bullets may pass + /// over terrain, but they cannot pass by each other; they destroy each other on collision. + /// + /// (Stats can be manually made to occupy the same x/y coordinates, but although this technique + /// is known as "stat stacking", strictly speaking ZZT has no way to represent one stat being + /// above or below another. The combination of stats in this way does not behave like two + /// overlapping items.) pub under: Tile, + /// Current position in an object's ZZT-OOP program. + /// + /// This is a byte offset in the file format, which corresponds to a character offset in the + /// `String` representation. 0 starts from the top of the program and is the typical default. + /// + /// ZZT uses -1 to indicate that execution has halted; this value can be set from within ZZT + /// using the `#end` command, but it can also be set directly in the file format to keep an + /// object from running its code when the board is first loaded. + /// + /// ZZT has no call stack, so this is the main piece of execution state. pub instruction_pointer: i16, + /// The stat's ZZT-OOP program, if any. + /// + /// If a stat doesn't have a program, this is set to the empty string. This field is only ever + /// used by scrolls and objects, so it's pretty common for this to be empty. pub program: Program, }