Templates and Gameplay Systems

Templates#

A template is a complete project skeleton: an assets/ folder, a server/ folder, game_config.json, project.vastopia, and optionally a root template.json manifest. Creating a game copies the template to a new folder and then shapes the copy with your choices from the New Project page. See Create your first game for the page itself and Project structure for what the copied folder contains.

Every template belongs to one of three categories, which is the first thing the template gallery groups by: Diversion, Quest and MMO. Choosing a template is required; the Basics step does not advance until you pick one, and shows "Choose a template to start from." if you try.

The three bundled starters#

Three starters ship inside the editor and are always listed first, badged "Included with the editor · no download". They share the same sample world (the same map, NPCs and items) and differ only in which gameplay systems survive creation:

This is a real difference on disk, not a label. Because switching a system off deletes its files, an Arena Starter project genuinely has no quest module, no shop schema and no trade interface, and its tab bar loses the matching tabs. The systems a starter pre-selects are only the starting point: the Systems step lets you toggle any of them before the project is created.

Published templates#

The editor also asks the platform for published templates (GET /api/templates) and lists them under their category alongside the bundled three. A category with nothing published shows "No <category> templates published yet." The catalog request is fire-and-forget: if you are offline or signed out, the bundled starters are still there and the last fetched catalog is reused from the editor's cache.

A published template card shows its version and size ("v1.0.0 · 42 MB download", or "v1.0.0 · downloaded" once it is cached). Selecting one downloads it when you leave the Basics step, verifies the archive's SHA-256 against the catalog, and extracts it into the editor's user data under project_templates/<id>/<version>/. Subsequent projects from the same template version reuse that folder. If a download fails, the gallery says "That template could not be downloaded. Pick another, or use the included starter."

A published template's template.json carries {id, name, version, category, default_systems}. default_systems decides which systems start checked on the Systems step for that template. The bundled starters have no manifest; their presets come from the editor itself.

Gameplay systems#

A gameplay system is not a switch inside the engine. It is a named set of files in your project: a server module, some scripts, a schema folder, an interface scene, a tab entry. Turning a system off removes those files; turning it on puts them back. The registry that maps each system to its files is fixed in the editor, so the list below is the complete set.

Systems are grouped into five categories, listed in the order the editor shows them: World, Progression, Economy, Social, Combat.

System reference#

File paths are relative to the project root. Tabs refer to interface_name entries in assets/data/tab_config.json that are removed when the system is off.

Interface paths are under assets/interface/screens/; schema folders are under server/schemas/. The tools that author content for these systems are described in Loot tables, Skills, Shops, Recipes, Tasks and quests and Dialogue.

Dependencies#

Four systems require another one: Quests needs Dialogue; NPC Aggression, Special Attacks and Bosses need Combat. The Systems step enforces this in both directions and says what it did rather than correcting silently:

• Turning on Quests also turns on Dialogue ("Dialogue also turned on — Quests needs it.").
• Turning off Combat also turns off Aggression, Specials and Bosses ("Bosses also turned off — it needs Combat.").

Each dependent system also carries a "needs Combat" (or "needs Dialogue") line under its description.

Protected tabs#

Three tabs can never be removed by a system: inventory, equipment and skills. The client hard-codes those to its own built-in scenes, so they stay in tab_config.json whatever you switch off. See Tabs.

Shared files are kept#

When a file or folder is owned by more than one system, it is only deleted when every owner is off. The removal set is "everything the disabled systems own, minus anything an enabled system also owns".

Server-enforced systems#

Turning most systems off is complete the moment their files are gone. Three are different: Shops, Player Trading and Combat carry a "server-enforced" badge on the Systems step (hover it for the explanation).

The reason is a server detail worth knowing. The game server ships pre-compiled copies of eight modules (trade, shops, combat, movement, npc, player, player-interaction, world). A game module with the same id overrides the built-in one, but when the game ships no file at all the built-in copy loads instead. So deleting TradeModule.cs from your project makes trading vanish in a local Dev Test (which has no built-in copies) while a deployed game server silently keeps trading alive.

To close that gap, creating a project also writes server/data/systems.json:

{
	"version": 1,
	"enabled_systems": ["dialogue", "quests", "..."],
	"disabled_systems": ["trading"],
	"disabled_modules": ["trade"]
}

disabled_modules is the list that actually enforces anything: the server refuses to load any module whose id appears there, built-in or not. enabled_systems and disabled_systems are informational. A missing file means "load everything", which is how every game behaved before the file existed, and a malformed file is ignored rather than stripping a live game of its combat. The file is part of the server package uploaded with every build, so the decision reaches your game servers on the next Push to Test.

The module ids each system records when it is off:

Tasks & Achievements and Banking ship no server module of their own, so they record no module id.

Where the choice is stored#

The enabled set is persisted in two places, written together:

Whenever the list is written it is first closed over dependencies, so [systems] enabled never lists Quests without Dialogue.

When the choice is applied#

The systems are applied once, while the template is being copied into the new project folder. There is no screen in the editor for changing the set afterwards, so treat the Systems step as a decision rather than a setting.

What "applied" means, at creation:

• Every file and folder owned by a system you left off is deleted from the copied template, unless a system you kept also owns it.
• Tabs belonging to those systems are stripped from tab_config.json; the tab bar's width and spacing are left as you laid them out on the Tabs step.
• server/data/systems.json and [systems] enabled are written with the resolved set.

Export a project as a template#

You can turn any open project into a template zip, either to reuse it as your own starting point or to hand to the platform for publishing.

1. With the project open, choose Project ▸ Export as Template....
2. In the Export Project as Template dialog, pick where to write the .zip. The suggested file name is the project name in lowercase with dashes.
3. Click save. A dialog reports "Template written: <file> (N files)." along with the command used to publish it.

The export writes a template.json manifest into the project root before zipping, with id (the project name in lowercase with dashes), name, version (1.0.0) and default_systems set to the project's currently enabled systems. That file stays in your project afterwards. The zip contains every top-level folder except packs/ and anything dot-prefixed (build output and caches), plus every root file that is not a temp or backup file.

Publishing a template to the public catalog is a platform-admin operation performed with a script on the API side; the editor does not upload templates itself. The bundled starters are always available regardless of what the catalog holds.

With AI (MCP)#

There is no MCP tool for templates or system toggles. create_project scaffolds a minimal skeleton (project.vastopia, assets/, server/) in the MCP workspace rather than copying a template, so it carries no systems choice; use the editor's New Project page when you want a starter world and a curated set of systems. get_project_config returns every section of project.vastopia, including [systems] when present.