This project is a tabletop roleplaying game set at Hogwarts School of Witchcraft and Wizardry. It is built on a structured file system: every spell, character, location, class session, school day, and house cup exists as a named file with typed fields. The GM (and the AI assistant) read these files to understand the world state, and write to them as the story progresses.
This manual explains how the project is put together, what each file type does, and how to extend it without breaking the existing structure.
The File System at a Glance
The project organizes content into folders (one per content type) and file types (registered schemas that define what fields a file can have). You do not need to memorize this — the file type list is always visible in the project — but it helps to see the full picture.
| Folder | File Type | Purpose |
|---|
/Characters/ | character | Students and staff — the people in the world |
/Spells/ | spell | Every spell available in the game |
/Equipment/ | equipment | Wands, robes, potions ingredients, and other items |
/Locations/ | location | Places in the wizarding world (castle, village, etc.) |
/Houses/ | house | The four Hogwarts Houses with their point totals |
/House Cups/ | house-cup | Annual House Cup competitions and results |
/School Years/ | school-year | The seven years of the Hogwarts timeline |
/Days/ | day | Individual school days within each year |
/Class Sessions/ | class-session | Specific classes attended by characters |
/Factions/ | faction | Groups and organizations (Order, Death Eaters, etc.) |
/Lore/ | lore | World-building notes and historical entries |
/Game Starts/ | game-start | Pre-built starting scenarios for new campaigns |
/GM Instructions/ | gm-instructions | Markdown files the GM agent reads during play |
How References Work
File types use reference fields to link to other files. For example, a character's house field stores a slug like gryffindor that points to the corresponding house file. A class session's day field links to a specific day file. These references keep the data connected without duplicating information.
When you create a new file that references another, use the target file's slug as the value. The platform resolves the reference automatically. Do not invent UUIDs or reference IDs — use human-readable slugs.
The Role of Each File Type
The project distinguishes between different kinds of content:
Entities are the nouns of the world — characters, spells, equipment, locations, factions. They have stats, descriptions, and images. They are what players interact with.
Timeline files track the progression of the school year — school years, days, and class sessions. They form a chain: a school year contains days, days contain class sessions, and each class session may reference a spell learned or a location visited.
Structural files track ongoing state — houses (with point totals), house cups (with standings), and game starts (with campaign configuration).
Narrative files are freeform content — lore entries and GM instructions. They are markdown, not JSON, and carry the story and guidance rather than structured data.
Understanding this distinction matters when you are adding new content. A new spell is an entity. A new school year milestone is a timeline event. A new faction is an entity with relationships. Choose the right type for what you are creating.
The GM Instructions System
GM Instructions are markdown files that the Game Master agent loads during play. They are not player-facing — they contain rulings, adjudication guidance, and world secrets that the players should not see.
Each file has a trigger in its frontmatter that tells the AI when to load it. For example, a combat adjudication file triggers when combat begins; a magic system file triggers when a player casts a spell.
If you need to add a new GM instruction, create a .gm-instructions.md file in the /GM Instructions/ folder with a descriptive trigger in the frontmatter. Write it as a guide for the GM, not as a rulebook for players.