Package Model

Required files

Optional files

• prompts/generated_scene_image_system_prompt.txt when the game uses hosted generated-scene image prompting
• prompts/additional_special_scene_instructions.txt for a short final user-prompt addendum on generated-scene image requests
• prompts/special_background_image_system_prompt.txt when the game uses generated reusable background plates
• prompts/additional_special_background_instructions.txt for reusable generated-background addendum text
• prompts/protagonist_avatar_image_system_prompt.txt and prompts/protagonist_avatar_image_user_prompt.txt when the game supports generated protagonist avatars
• prompts/additional_instructions.txt for MGPT additional instructions that can be frozen into universe generation contracts
• openings/opening_states.<locale>.json for localized opening-state data when supported, with Portuguese kept at openings/opening_states.pt.json for compatibility

Package folders

• manifests/ stores package metadata and runtime UI configuration.
• prompts/ stores runtime, image, avatar, and addendum instruction files.
• schemas/ stores the structured-output contract.
• openings/ stores opening-state data.
• assets/ stores game-owned images, audio, and other published files.

Published asset rules

Runtime-required files are always included in the inventory. Assets are opt-in. Only paths matched by assets.published in manifests/game-definition.json are considered part of the hosted package inventory.

{
  "assets": {
    "published": [
      "images/backgrounds/**",
      "images/ui/**",
      "audio/*.mp3",
      "audio/sfx/*.wav"
    ]
  }
}

Patterns are relative to the assets/ root. Files that are not matched stay local by default, which keeps work-in-progress references and authoring assets out of the hosted runtime.

Public source package exports

Public read-only workspaces can expose a downloadable source package. For non-owner exports, files under prompts/ are replaced with generic functional instructions so the package structure, schema, openings, and assets remain inspectable without revealing production instruction IP.

Owner and admin exports include the real prompt files. Public exports include a README listing which instruction files were replaced.

Deterministic inventory

`mdl diff` and `mdl push` both use the same deterministic inventory model. Path normalization, file hashing, published asset filtering, and hosted path mapping are shared across local and remote operations.

• Hashes are content-based and stable.
• File ordering is normalized before the container hash is computed.
• The same package contract powers local inspection and hosted pushes.

Design for Git and agents

The package contract is intentionally file-oriented. That keeps changes reviewable, diffable, and safe to edit with code agents instead of burying core game logic in opaque binary blobs or ad hoc editor state.

Next