Page 9 · Experiences

Experiences & Worldgen

Turn a datapack into a launchable game with owned saves, startup actions, world presets, server-owned bootstrap, global installation, and an experience-owned interface.

Experience Definitions

Store experience profiles under data/<namespace>/dai_experiences/*.json.

{
  "enabled": true,
  "priority": 1000,
  "save_id": "My Adventure",
  "save_name": "My Adventure",
  "create_if_missing": true,
  "load_if_existing": true,
  "auto_create": true,
  "worldgen": "my_pack:journey",
  "on_first_join": "my_pack:first_join",
  "on_join": "my_pack:resume",
  "ui": {
    "auto_enable": true,
    "grave_cursor_toggle": true,
    "open_dai_menu_on_grave": false,
    "grave_open_action": "my_pack:open",
    "grave_close_action": "my_pack:close",
    "grave_anchor_overlay": "main_frame"
  }
}

Experience-Owned Grave / Backtick UI

When open_dai_menu_on_grave is false, an experience can own DAI's grave/backtick key. grave_open_action rebuilds the game UI, grave_close_action removes it, and grave_anchor_overlay gives DAI a concrete visual state to test when deciding whether the interface is open.

Experience UI open → press ` → close action → cursor recaptured
Experience UI closed → press ` → open action → cursor released

If explicit open/close actions are omitted, DAI can use the <namespace>:open and <namespace>:close convention where supported.

Worldgen Profiles

Store world bootstrap profiles under data/<namespace>/dai_worldgen/*.json. The world_preset points at a normal Minecraft world preset; DAI adds experience-friendly spawn/bootstrap data around it.

{
  "enabled": true,
  "world_preset": "minecraft:flat",
  "seed": 0,
  "spawn": {"x":0,"y":200,"z":0,"yaw":0,"pitch":0},
  "generation_commands": ["time set day"],
  "initial_structures": [],
  "bootstrap_actions": []
}

Startup Lifecycle

Discover experience + worldgen early
        ↓
Create or load owned save
        ↓
Apply server worldgen bootstrap once
        ↓
Join player
        ↓
First join? → on_first_join
Returning?  → on_join
        ↓
Mark startup dispatched on server

Use on_first_join for one-time onboarding and on_join for repair/resume logic that is safe to run every time.

Functions Are Excellent Server-Owned Building Blocks

When a large authoritative operation already fits naturally in Minecraft commands, keep it in a datapack function and call it with server_run_function. You do not need to translate every setblock or scoreboard command into a Java-side direct action.

Global Installation in 3.0

Players can place an experience datapack in <gameDir>/datapacks/. DAI can discover supported experience/title/worldgen data there before a world opens, then copy and enable the pack inside the owned save when that experience launches.

Global does not mean enabled everywhere. The root folder is a DAI library. Vanilla still loads the gameplay datapack from the target world's datapacks directory.

Creator Support

The 3.0 Creator has first-class Experience & Worldgen editors. For normal Minecraft world presets, structures, dimension data or other vanilla data types, use the Universal Files workspace in the same project.

Experience Control Ceilings

The active main experience can provide a small optional controls object for autonomous DAI capabilities and performance. These values are ceilings: the player's own config can always be stricter.

"controls": {
  "automation": true,
  "automation_movement": true,
  "automation_combat": true,
  "automation_world_editing": true,
  "max_actions_per_second": 10,
  "max_action_queue_size": 128
}

Legacy-safe. If controls is absent, DAI uses permissive defaults matching older experience behavior.

3.0 MAIN Experience Branding

The optional branding object lets one MAIN experience carry its identity from application startup into world entry. The flat loading fields remain the shared defaults; early_loading and world_loading may override individual stages.

{
  "branding": {
    "window_title": "My Game",
    "companion_id": "my_game",
    "custom_loading_screen": true,
    "loading_background_texture": "my_game:textures/gui/loading.png",
    "loading_logo": "my_game:textures/gui/logo.png",
    "loading_accent": "#65E6B4",
    "use_resource_pack_icon": true,
    "early_loading": {
      "enabled": true,
      "hide_mojang_logo": true,
      "show_progress": true,
      "show_startup_log": false
    },
    "world_loading": {
      "enabled": true,
      "title": "ENTERING WORLD",
      "subtitle": "Preparing sector...",
      "show_progress": true,
      "show_status_text": true,
      "include_transitions": true
    }
  }
}

Lifecycle rule: branding replaces presentation, not Minecraft's loading lifecycle. Early FML theming is synchronized after the MAIN is discovered and therefore becomes visible on the next JVM launch.

Native Generated World Data

Worldgen profiles can coexist with dai_biomes, dai_dimension_types, dai_timelines, dai_dimensions and Mojang worldgen bridge folders. DAI compiles them into the generated server-data pack before the experience world is created.

MAIN Experiences Inside Mod JARs

DAI's early experience/worldgen discovery now scans installed mod JARs in addition to world and global datapacks. A mod can therefore ship a complete DAI MAIN experience using the same data/<namespace>/dai_experiences, dai_title_screens, worldgen and native-content folders used by a standalone datapack.

mods/MyDAIGame.jar
└─ data/my_dai_game/
   ├─ dai_experiences/main.json
   ├─ dai_title_screens/main.json
   ├─ dai_worldgen/world.json
   └─ dai_items/...
        ↓
Early MAIN discovery
        ↓
Registry/world-data preparation
        ↓
Normal DAI runtime reload

No world-copy requirement for the mod-owned MAIN. The JAR is already an installed data source, so DAI can discover it directly rather than treating it as another global ZIP that must be mirrored into the save.