Puzzle

Nine ready-made puzzle mechanics, declared as quest objectives and rendered client-side.

The Puzzle Extension turns a location in your world into a solvable puzzle. Each puzzle is a Typewriter objective: it starts when the player enters its audience, tracks progress per player, and fires triggers on completion, failure or timeout — so a puzzle plugs into a quest exactly like any other objective.

Everything a puzzle draws is client-side: blocks, ghost previews, highlights and laser beams are sent to the player who is solving it. Two players can work on the same lever board without seeing each other's progress, and the real world is never modified.

Key features

• Nine puzzle types — block pushing, pedestal offerings, memory sequences, lever orders, pattern placement, item frame rotations, combination locks, laser grids and cooperative pressure plates.
• Per-player, or shared — isShared switches a puzzle from private progress to one board the whole group advances together.
• Client-side rendering — no world edits, no rollback to write, no interference between players.
• Full objective lifecycle — onStart, onComplete, onFail, onTimeout and onLifespanExpire triggers, plus time limits, attempt limits and fail cooldowns.
• Chaining — puzzle_chain runs several puzzles in order and fires once the whole sequence is solved.
• Survives restarts — puzzle_artifact persists puzzle state, so a reboot mid-puzzle does not erase progress.
• Readable state — puzzle_solved_fact and puzzle_active_fact expose progress to the rest of your content.
• Folia-safe — every world read and write runs on the region that owns the puzzle.

Fields shared by every puzzle

All nine puzzle objectives inherit the same lifecycle fields. Only the puzzle-specific fields are listed on each entry page.

Field	Type	Description
id	String	Identifier used by chains, facts and the puzzle menu.
fact	Ref<CachableFactEntry>	Fact holding the player's progress.
amount	Var<Int>	Number of completions required.
timeLimit	Var<Int>	Seconds allowed before onTimeout fires. 0 = no limit.
cooldownOnFail	Var<Int>	Seconds before the player may try again after a failure.
maxAttempts	Var<Int>	Attempts allowed before the puzzle fails. 0 = unlimited.
resetOnWrong	Var<Boolean>	Whether a wrong step resets progress.
showHints	Var<Boolean>	Whether hintMessage is shown while solving.
hintMessage	Var<String>	Hint text. Supports {progress} and {total}.
completionMessage	Var<String>	Message sent when the puzzle is solved.
onStart	Ref<TriggerableEntry>	Fired when the puzzle becomes active for the player.
onComplete	Ref<TriggerableEntry>	Fired when the puzzle is solved.
onFail	Ref<TriggerableEntry>	Fired when the puzzle fails.
onTimeout	Ref<TriggerableEntry>	Fired when timeLimit elapses.
onLifespanExpire	Ref<TriggerableEntry>	Fired when lifespan elapses.
lifespan	Var<Int>	Seconds the puzzle stays active. 0 = forever.
isShared	Var<Boolean>	true = one shared board; false = per-player progress.
criteria	List<Criteria>	Conditions a player must meet for the puzzle to apply.

Entries

Objectives

Entry	Description
puzzle_block_push	Push blocks into their target holes.
puzzle_pedestal	Offer the right item on a pedestal.
puzzle_memory	Repeat a highlighted button sequence.
puzzle_lever_order	Flip levers in the correct order.
puzzle_pattern	Reproduce a block pattern on a grid.
puzzle_item_frame	Rotate item frames to the right angles.
puzzle_combination_lock	Enter a digit code in order.
puzzle_laser_grid	Route beams into their receivers.
puzzle_coop_pressure	Hold pressure plates together.

Triggers

Entry	Description
puzzle_chain	Runs several puzzles in order.
puzzle_menu	Opens a chat menu listing puzzles.

Artifacts

Entry	Description
puzzle_artifact	Persists puzzle state across restarts.

Facts

Entry	Description
puzzle_solved_fact	Whether a puzzle is solved for the player.
puzzle_active_fact	Whether a puzzle is currently active for the player.