Trigger Events, Dialogue Mechanics & Canonical 8-Stage Level Saves
Both the VR Inner City Live 3D Studio (/vr?edit3d=1) and the Admin Planets Command Center (/admin-planets) share 100% option parity and execute the Canonical 8-Stage Save Order. Saving in either editor fetches the latest database baseline first, deep-merges scene items, NPC Studio paths, cinema scripts, dialogue triggers, branching choices, and multi-goal triggers by ID without ever overwriting or canceling out the other editor, and broadcasts live updates across iframes and browser tabs.
[warp_planet:mars]
πͺ Warp to MARS=>action:warp_planet:mars::Locking coordinates!
Canonical 8-Stage Save Order & Non-Destructive Deep Merge
Whenever you click πΎ Save All Changes to Planet DB in vr-inner-city.html or πΎ Save Planet Scene & Layers in admin-planets.html, both editors and the backend handler (handleSavePlanetSceneConfig in auth-backend/core.js) process the save in the exact same 8-Stage Order:
Saves planet_id, name, planet_class, star_system_id, sky_color, horizon_color, ground_color, ground_color2, ground_type, atmosphere_fog, gravity, topographical_altitude, floor_depth, and custom_aframe_markup.
Deep-merges skybox_env_config (procedural/HDRI/3D dome, clouds, weather particles, foliage, custom audio playlist) and post_processing_config (shader presets, outlines, vignette, saturation).
Normalizes planet_access_config and writes both alias sets (price_amount + entry_price_amount, price_currency + entry_price_currency, require_portal_trigger + require_portal).
Deep-merges giants_config, nested hit_affect (damage flash, tint color, scale pulse), and throw_mechanics without losing sub-fields.
Deep-merges oogaloo_config, preserving crew_members[], victory_triggers[], goal_triggers[], and world_dialogues_json by ID.
Runs mergePlanetSceneItemsArrays by item id. Unmodified built-ins never overwrite modified items; rich NPC Studio, Path, Cinema, Trigger, Choice, Portal, and WB Episode fields are preserved.
Synchronizes merged_mechanics (tower_defense, world_builder, fighting_arena, card_clash, arcade_hooks) and mirrors scene_items_config.
Persists descentLayers[] and mirrors all 8 stages into planet.metadata so both top-level and metadata readers always receive identical state.
Before saving, both editors fetch the latest GET /api/planets/scenes/:planetId baseline. If an item was edited in vr-inner-city.html (`is_modified: true` or rich trigger/NPC fields set), an unmodified default item from admin-planets.html is blocked from overwriting it.
Both editors and backend automatically mirror portal_enabled β is_portal, portal_target_planet β portal_planet_id, dialogue β dialogue_lines, anim_clip β idle_clip, and price_amount β entry_price_amount.
Every save broadcasts a BroadcastChannel('sodas-planet-save-sync') + postMessage event so if both editors are open in different tabs or embedded iframes, the other editor reloads the saved state immediately.
Event Trigger Keywords (event_trigger_on & event_action_type)
A. When Event Fires (event_trigger_on)
| Keyword | When It Fires |
|---|---|
| on_talk_or_click | When player clicks the NPC/entity or presses [E] near them. |
| on_proximity | Automatically when player enters dialogue_trigger_distance (default 9m). |
| on_dialogue_end | Fires as soon as the NPC finishes speaking their dialogue line/sequence. |
| on_attack_hit | When the player strikes the NPC/prop with a melee attack or weapon projectile. |
| on_defeat | When this specific NPC or enemy entity's HP reaches 0. |
| on_enemy_kills | Fires when the player's kill count reaches the threshold in event_action_param. |
B. Event Action Keywords (event_action_type & event_action_param)
| Action Keyword | Parameter Format (event_action_param) |
Effect |
|---|---|---|
| warp_planet | mars or portal:jupiter:7 | Warps player directly to the target planet (or spawns a glowing portal ring if prefixed with portal:). |
| warp_level | vr-outer-city or vr-house or td | Transitions to another VR level/scene (vr-inner-city, vr-outer-city, vr-house, scl-three-infinite, tower-defense, rpg). |
| goto_page | /world or modal:/store or newtab:/docs | Navigates to any app route, opens an in-VR glass iframe overlay (modal:/path), or opens a new tab (newtab:/path). |
| script_mechanic | low_gravity_jump or awaken_giants | Executes one of the 15 built-in gameplay mechanics or custom JS hook (see Section 4 below). |
| complete_goal | goal_vanguard_kills | Immediately marks the matching Goal ID in oogaloo_config.goal_triggers as completed and grants its rewards. |
| give_rewards | 500,2 | Grants credits,hearts (e.g. 500,2 = +500 Credits & +2 VR Hearts). |
| open_choice_prompt | (uses choice_prompt & choices_json) | Opens the interactive branching decision modal for this NPC. |
| open_portal_warp | /vr?planet=saturn&tier=6 | Spawns an interactive glowing warp gate at the NPC/entity's coordinates. |
| trigger_giants_attack | awaken | Awakens all Skybox Giants into active siege/throw mode. |
| set_crew_stance | dance or aggressive or friendly | Switches the planet's Oogaloo Stage Crew between dance party, friendly ally, or combat wave mode. |
| play_anim_clip | M_F_Dance_001 | Crossfades the NPC's 3D AnimationMixer to the specified GLB or Mixamo M_ animation clip. |
| launch_wb_episode | ep-1-citadel-breach | Launches the linked WorldBuilder Story Episode or inline wave event. |
| chain_world_dialogue | dlg_citadel_intro | Fires a sequence entry from the planet's World Dialogue Table by dialogue_id. |
Inline Dialogue Bracket Tags ([tag:param]) & Branching Choice Syntax
You can embed bracket tags directly inside an NPC's dialogue / dialogue_lines (separated by |). When the NPC speaks that line, the bracket tag is stripped from the visible speech bubble and executed automatically:
Welcome to Citadel Sector 7! | Clear the vanguard! [complete_goal:goal_vanguard_kills] | Step through to Mars! [warp_planet:mars]
- [warp_planet:mars] β Warps to planet
mars - [warp_planet:portal:jupiter] β Spawns portal ring to
jupiter - [warp_level:vr-outer-city] β Switches VR level to Sky Layer
- [goto_page:modal:/world] β Opens
/worldin an in-VR modal - [script_mechanic:low_gravity_jump] β Triggers Low-G Jump
- [complete_goal:goal_1] β Completes
goal_1 - [reward:500,2] β Grants +500 Credits & +2 Hearts
choices_json)
Enable choice_enabled on any NPC or World Dialogue entry and define options separated by | using the format Button Label=>action:type:param::NPC Reply Speech:
πͺ Warp to Mars=>action:warp_planet:mars::Locking warp coordinates! | πΊοΈ Sky Layer=>action:warp_level:vr-outer-city::Ascending to Tier 7! | π World Hub=>action:goto_page:modal:/world::Opening World Hub! | βοΈ Low-G Jump=>action:script_mechanic:low_gravity_jump::Thrusters online!
- Shthand Rewards:
Claim Drop=>reward:350,2::Supplies granted! - Direct Action:
Awaken Giants=>action:trigger_giants_attack::The Giants awaken! - 1-Click Builder: Use the π 1-Click Attach Goal, Planet Warp, Level, Page or Script bar in either editor to generate both inline tags and choice buttons automatically.
Built-in script_mechanic Presets, VR Level Slugs & Page Modals
- low_gravity_jump β Sets moon gravity (-4.8 m/sΒ²) & high jump impulse
- zero_g_float β Enables zero-G levitation & upward drift
- hyper_gravity β Heavy crush gravity (-38 m/sΒ²)
- speed_boost β 2.2x sprint speed multiplier for 30s
- heal_full β Restores 100% Player HP & +2 VR Hearts
- grant_shield β Activates reflective Forcefield Shield
- spawn_reinforcements β Spawns allied/wave Oogaloo units
- clear_wave_enemies β Eliminates all active wave hostiles
- awaken_giants β Awakens all Skybox Giants
- pacify_giants β Returns Skybox Giants to peaceful idle
- crew_dance_party β Switches Stage Crew to
M_Danceparty - crew_battle_mode β Switches Stage Crew to combat stance
- neon_storm_sky / disco_lights / earthquake_shake
- vr-inner-city β
/vr?planet=X&tier=6 - vr-outer-city β
/vr-z?planet=X&tier=7 - vr-house β
/vr-house?planet=X - scl-three-infinite β
/scl-three-infinite - tower-defense β
/games/tower-defense/index.html - modal:/world β Opens route in glass HUD modal
- newtab:/store β Opens route in new browser tab
Enemy Kill Counts, Distinct Enemy Types & Multi-Goal Triggers (oogaloo_config.goal_triggers)
Every planet supports an array of simultaneous mission objectives in oogaloo_config.goal_triggers[]. The live HUD tracks total enemies killed (totalKills), kills per category (killsByType: oogaloo, giant, boss, drone, custom_npc), and distinct enemy types defeated (distinctTypesKilled).
Goal Condition (condition_type) |
Required Fields | Description & Completion Rule |
|---|---|---|
| enemies_killed | target_kills: 5, enemy_type_filter: "all" | "oogaloo" | "giant" | "boss" | Fires when the player defeats target_kills enemies matching enemy_type_filter. |
| enemy_types_killed | target_enemy_types: 3 | Fires when the player defeats at least N different enemy archetypes (e.g., 1 Oogaloo + 1 Skybox Giant + 1 Boss = 3 distinct types). |
| kills_and_types | target_kills: 8, target_enemy_types: 2 | Combined mastery goal: requires both total kill threshold AND minimum distinct enemy types defeated. |
| talk_to_npc | target_npc_id: "npc-1" | Fires when the player speaks with the specified NPC ID or when an NPC dialogue triggers [complete_goal:ID]. |
| defeat_specific_npc | target_npc_id: "boss-overlord" | Fires when the specific named boss or custom NPC entity is defeated. |
| reach_point | target_coords: "0 18 -32", radius: 6 | Fires when the player's 3D rig enters within radius meters of the target coordinates. |
Level Save Keywords & Property Dictionary
| Save Stage / Object | JSON Keyword / Property | Type / Default | Usage across VR Inner City & Admin Planets |
|---|---|---|---|
| Stage 6: scene_items_config.items[] | id, dom_id, category, scene_scope | string ("inner"|"outer"|"both") | Unique item identifier, A-Frame DOM selector, category (HOUSING, FACILITY, NPC_PROP), and visibility scope. |
| Stage 6: scene_items_config.items[] | x, y, z, position, rot_y, rotation, scale | number / Vec3 string | 3D world transform coordinates, Euler Y rotation, and XYZ scale string ("15 15 15"). |
| Stage 6: scene_items_config.items[] | is_modified, is_deleted, _explicitlyRestored, updated_at_ms | boolean / timestamp | Tracks user modifications vs unmodified built-in defaults so neither editor ever clobbers the other's edits. |
| Stage 6: NPC Studio | npc_name, anim_mode, anim_clip (idle_clip), walk_clip, talk_clip, anim_sequence | string | Dynamic NPC display name, animation state machine mode (auto_state, loop_single, sequence), and clip assignments. |
| Stage 6: 3D Pathing | path_mode, waypoints, path_speed, waypoint_pause_sec, path_radius | string / number | Controls 3D patrol routes (stationary, loop, pingpong, once, wander) and pipe-separated x y z | x y z waypoints. |
| Stage 6: Proximity & Cinema | dialogue (dialogue_lines), dialogue_audio_urls, npc_conv_enabled, npc_conv_script | string / boolean | Player proximity speech lines, speech audio URLs, and autonomous NPCβNPC cinema banter scripts (SELF: ... | PARTNER: ...). |
| Stage 6: Event & Choice Triggers | event_trigger_on, event_action_type, event_action_param, choice_enabled, choice_prompt, choices_json | string / boolean | Attaches planet warps, level warps, page modals, script mechanics, goal completions, and branching choice prompts to any entity. |
| Stage 6: Portals & Episodes | portal_enabled (is_portal), portal_target_planet (portal_planet_id), portal_price_amount, wb_episode_slug | boolean / string / number | Turns any building, door, or NPC into a planetary warp gate or WorldBuilder story episode trigger. |
| Stage 5: oogaloo_config | goal_triggers[], victory_triggers[], world_dialogues_json, crew_members[] | array / string | Stores multi-goal kill/type objectives, boss victory triggers, world dialogue table, and stage crew roster (deep-merged by ID). |
| Stage 3: planet_access_config | is_free, price_amount (entry_price_amount), price_currency (entry_price_currency), unlock_mode | boolean / string | Configures planetary entry toll in Credits/Sparks or Free public access, mirrored across both alias key sets. |