Skip to content

docs: add a Gates guide and bring the Doors guide up to date - #20

Merged
Kheartz merged 4 commits into
hogwarts-mp:mainfrom
Kheartz:gates-guide
Oct 24, 2026
Merged

Kheartz merged 4 commits into
hogwarts-mp:mainfrom
Kheartz:gates-guide

Conversation

@Kheartz

@Kheartz Kheartz commented Oct 19, 2026

Copy link
Copy Markdown
Member

Adds a Gates guide to the World section, brings the Doors guide up to date, and links the two.

The Gates guide covers:

  • that gates are not doors: no Doors call reaches a gate, and no Gates call reaches a door;
  • the four kinds and what each supports: portcullis (opens, closes, locks), runeGate (opens past its puzzle, closes), swingGate (opens, closes) and crawlGrate (opens one way, by breaking);
  • client Gates.list and its row fields, setOpen, setLocked, freezeSchedule, setPolicy, policy() and held();
  • server Gates.set / get / list / clear / clearAll, and how held state combines with the policy;
  • the doors resource's gates: rules (kind, open, lock), heldGates, gateSchedule and the gate commands;
  • gotchas: the Clocktower gate's three actors, scoping wide opens with kind, freezing portcullis schedules, and gates a player opens their own way not being shared.

The Doors guide gains:

  • a pointer to Gates;
  • a section on shared unlocks: Doors.setShareUnlocks / getShareUnlocks and the doorUnlocked event;
  • doorUnlockRequest details: at most once a second per door, the other leaf of a double door, and an empty selector for a lock the player's own policy keeps shut;
  • holding both leaves of a double door;
  • "key-only locks included" for the master key (superAlohomora);
  • a section on the doors resource: the held config, /listdoors, /doorset and /doorsheld;
  • a fix: unlocking with Doors.set unlocks the door for everyone. It does not open it.

The overview lists the new guide under World.

Depends on a contract republish. The Gates API landed on mod main in 718af20e, but the published testing contract is still 1.9.2, which has no Gates. Until a contract from that commit or later is published, docs:check fails on the five Gates samples:

guides/World/gates.md:31:22 - TS2304 (client): Cannot find name 'Gates'.
guides/World/gates.md:61:1 - TS2304 (server): Cannot find name 'Gates'.
guides/World/gates.md:62:1 - TS2304 (server): Cannot find name 'Gates'.
guides/World/gates.md:86:16 - TS2304 (client): Cannot find name 'Gates'.
guides/World/gates.md:102:1 - TS2304 (client): Cannot find name 'Gates'.

The guides don't link into the API reference, so nothing here breaks while the reference lacks the Gates types.

Tested locally:

  • docs:check: all 183 samples type-check against a contract built from mod main 718af20e;
  • pnpm build and docs:links: every link and anchor on 50 pages resolves;
  • checked the built Gates and Doors pages: Gates sits between Doors and Loot in the sidebar, and every table and code block renders.

The 1.10 contract declares every DoorStateUpdate field required, though an
absent field leaves that axis alone, so these samples fail without a lockLevel.
Fence them as jsx until the Mod marks the fields optional.
Doors.set's lockLevel, what a held level does together with a held lock, and the level Doors.list reports on the client.
Their resource sections now describe Foundations' hmp-doors: its data/hmp-doors.json rules, lock levels, shared unlocks, held gates, gate schedule and /doors commands.
@Kheartz
Kheartz marked this pull request as ready for review October 24, 2026 21:41
@Kheartz
Kheartz merged commit 1c931dd into hogwarts-mp:main Oct 24, 2026
1 check passed
@Kheartz
Kheartz deleted the gates-guide branch October 24, 2026 21:41
@Kheartz Kheartz mentioned this pull request Oct 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant