lazarr-cd2025/CODE_DOCUMENTATION.md

Code Documentation for Lazarr!

This file documents the code of this game. This file is still in WIP.

Coding rules

Some general rules for developing this game apply:

1. Nodes
   1. All nodes incompatible with lasers MUST have the laser_incompatible=1 group (see below)
   2. Nodes MUST NOT drop multiple items (for lzr_protection)
2. Lasers
   1. The "ends" of any laser node MUST NOT be visibly exposed to the player; they MUST either connect to another laser beam, or touch the side of a laser-compatible node. (thus rule does not apply in the editor or development mode)
   2. All lasers SHOULD look like a clean continuous beam; there SHOULD NOT be visible seams between laser nodes or anywhere else
   3. The 3 primary laser colors are red, green and blue
   4. Secondary colors are created by mixing:
      • red + green = yellow,
      • red + blue = magenta,
      • green + blue = cyan,
      • red + green + blue = white.
   5. Two colors are mixed by doing a logical OR between their primary color components. For example, red + yellow = yellow because yellow is made out of red and green.
3. Levels
   1. Levels must not use nodes with the laser_incompatible group
   2. Levels must have exactly one teleporter in off state
   3. Levels must have at least one treasure chest
   4. Player must not get stuck in a hole or be able to escape the level bounds (you may use lzr_core:barrier for the boundaries)

Laser compatibility

A node is said to be 'laser-compatible' when the visible laser beam will never end at a gap when it collides with the node from any side. Opaque full-cube nodes are laser-compatible, while air is laser-incompatible. Other drawtypes may or may not be compatible, depending on their shape and texture. To see if a node is compatible, shoot a laser to each of the node's sides. If the "end" of the laser is visibly exposed, i.e. not touching the node's visual border, it is incompatible. Otherwise, it is compatible.

Incompatible nodes are thus nodes where when the laser collides, there is a visible gap between the laser beam and the visual node.

Exception: If the node is immediately destroyed on contact or transformed into a compatible node, it counts as compatible.

Incompatible nodes can be also made compatible by adding variants of the node with a laser beam inside of them, and adding them as laser blocks in lzr_laser.

This is done for slabs and panes, for example.

Function reference

TODO

Node special fields reference

This is a list of special fields for node definitions that Lazarr! recognizes:

• _lzr_active: If the node has an 'active' counterpart, this contains the itemstring of that 'active' counterpart. Used by blocks that interact with laser
• _lzr_inactive: If the node has an 'inactive' counterpart, this contains the itemstring of that 'inactive' counterpart. Used by blocks that interact with laser
• _lzr_fixed: Node name of fixed (unmovable) variant of a laser block
• _lzr_rotatable: Node name of rotatable variant of a laser block (if it exists)
• _lzr_takable: Node name of takable variant of a laser block (if it exists)
• _lzr_next_color: Contains the name of the node with the next color in a sequence of colors, for the color change tool
• _lzr_prev_color: Same as _lzr_next_color, but for the previous color
• _lzr_on_toggle(pos, node): Function is called when this node is toggled on or off. This can happen either by a tool or a trigger (a node that triggers other nodes) pos is node position and node is node table
• _lzr_on_toggle_item(holding_player, item, slot): Same as lzr_on_toggle, but when the node is in item form in a player's inventory. holding_player is the player holding the item, item is the ItemStack to toggle, slot is the inventory slot in which the item resides (in the "main" list). MUST return the modified (or unmodified) ItemStack
• _lzr_unlock(pos, node): Function is called on chests to unlock it. pos is node position and node is node table
• _lzr_send_treasure(pos, node): Function is called on open chests with treasure to start an animation that "sends" the treasure into the sky. Used when a level is completed. pos is node position and node is node table

Node groups reference

See GROUPS.md for a reference of item groups used in this game.

Development mode and laser debug

There is a hidden development/debugging mode in this game. It is used to debug the behavior of lasers. The most useful tool is the laser stepper, which is like single-step debugging, but for lasers.

To enable the hidden debug mode, set the hidden setting lzr_debug to true in minetest.conf. This will unlock laser debug features:

• Chat commands:
  • /set_freeze_lasers: Enable/disable laser updates on map change
  • /force_laser_update: Recalculate all lasers
  • /clear_lasers: Removes lasers
  • /emit_lasers [<max. iterations>]: Emits lasers from emitters
• Tools (Only via /giveme)
  • Laser Absorber (lzr_tools:laser_absorber): Digs lasers
  • Laser Stepper (lzr_tools:laser_stepper): Simulates laser travel up to a set number of iterations. Basically a more convenient method for /emit_lasers

Development mode

Additionally, lzr_debug will also unlock the development mode. It can be accessed with the /devmode command. In this mode, the world can be altered more freely without the game getting in the way. Lasers are always frozen in development mode. You can also get all items in the inventory. This mode was created to test out stuff more easily.