lazarr_2025/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:

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)

Lasers: 3) 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. 3a) Rule 3 does not apply in the editor 4) All lasers SHOULD look like a clean continuous beam; there SHOULD NOT be visible seams between laser nodes or anywhere else 5) The 3 primary laser colors are red, green and blue 6) Secondary colors are created by mixing: red + green = yellow, red + blue = magenta, green + blue = cyan, red + green + blue = white. 7) 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.

Levels: 8) Levels must not use nodes with the laser_incompatible group 9) Levels must have exactly one teleporter in off state 10) Levels must have at least one treasure chest 11) 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_on_toggle(pos, node): Function is called when a special tool is used on this node. pos is node position and node is node table
• _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

This is a reference of all groups used for nodes.

Digging groups

• breakable=1: Node is breakable with Ultra Pickaxe
• punchdig=1: Node breaks when punched
• takable=1: Node can be taken by player to be placed somewhere else

Gameplay groups

• rotatable: Node is rotatable by hook item
  • 1: Always rotatable
  • 2: Rotatable if takable, or if in editor/menu
  • 3: Rotatable in editor/menu only
• laser_destroys: Node is destroyed when a laser touches it
  • 1: Immediate destruction
  • 2: Node catches fire first, then is destroyed. _lzr_active must contain the name of the burning variant. The burning variant in turn must have _lzr_inactive
• laser_incompatible=1: The node is "incompatible" with lasers. (see above)
• flammable=1: Node catches fire from neighboring burning blocks

Laser node groups

• laser=X: Node is a laser node, consisting of 1 to 3 laser beams (X = number uniquely identifying each possible combination of laser axes and colors) (not including blocks that interact with lasers like mirrors)
• laser_block=1: Node interacts with laser

Laser blocks

Group rating 1 is for the inactive state, group rating 2 is for the active state.

• emitter: Emitter
• detector: Detector
• crystal: Crystal
• mirror: Mirror (normal)
• transmissive_mirror: Transmissive Mirror
• hollow_barrel: Hollow barrel
• shy_skull: Shy Skull
• cursed_skull: Cursed Skull

Misc. categorization groups

• treasure=1: Treasure
• teleporter: Teleporter
  • 1: Off
  • 2: On
• chest: Chest
  • 1: closed, unlocked
  • 2: closed, locked
  • 3: open, empty
  • 4: open, with treasure
• chest_closed=1: Closed chest
• chest_open=1: Open chest
• chest_open_treasure=1: Open chest with treasure
• water=3: Water
• liquid=3: Node is a liquid in a semantic sense
• pane=1: Pane (flat window-like block)
• stair=1: Stair
• slab=1: Slab
• crate=1: Crate
• skull=1: Any skull (cursed or shy)

Item groups reference

This is a reference of groups for all items that are not nodes.

• pickaxe=1: Pickaxe
• bucket=1: Bucket
• cheat_item=1: Item is not supposed to be used in normal gameplay (e.g. for editor)