SCL NEXUS // LEVEL ARCHITECTURE & TRIGGER ENGINE MANUAL

πŸŽ―πŸ’Ύ Trigger Events & Level Save Keywords, Features & Usage Canonical 8-Stage Sync v2.0

Citizen Docs Mixamo & M_ Guide Admin Planets VR Inner City Studio
UNIFIED SAVE PARITY & INTERACTIVE TRIGGER ENGINE

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.

⚑ Interactive Trigger Tag Builder 1-Click Copy
Inline Dialogue Tag:
[warp_planet:mars]
Choice Button Option:
πŸͺ Warp to MARS=>action:warp_planet:mars::Locking coordinates!
Section 1 // Cross-Editor Save Architecture

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:

STAGE 1 // IDENTITY & PHYSICS

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.

STAGE 2 // SKYBOX & POST-FX

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).

STAGE 3 // PLANET ACCESS & PRICE

Normalizes planet_access_config and writes both alias sets (price_amount + entry_price_amount, price_currency + entry_price_currency, require_portal_trigger + require_portal).

STAGE 4 // GIANTS & HIT AFFECT

Deep-merges giants_config, nested hit_affect (damage flash, tint color, scale pulse), and throw_mechanics without losing sub-fields.

STAGE 5 // OOGALOO, DIALOGUE & GOALS

Deep-merges oogaloo_config, preserving crew_members[], victory_triggers[], goal_triggers[], and world_dialogues_json by ID.

STAGE 6 // SCENE ITEMS & NPC STUDIO

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.

STAGE 7 // MERGED MECHANICS & TD

Synchronizes merged_mechanics (tower_defense, world_builder, fighting_arena, card_clash, arcade_hooks) and mirrors scene_items_config.

STAGE 8 // DESCENT & METADATA MIRROR

Persists descentLayers[] and mirrors all 8 stages into planet.metadata so both top-level and metadata readers always receive identical state.

πŸ›‘οΈ How Conflicts Are Prevented

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.

πŸ”„ Automatic Alias Mirroring

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.

πŸ“‘ Cross-Tab & Iframe Live Sync

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.

Section 2 // NPC & Entity Event Triggers

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.
Section 3 // Dialogue-Driven Mechanics

Inline Dialogue Bracket Tags ([tag:param]) & Branching Choice Syntax

1. Inline Dialogue Bracket Tags (Embed in Any Spoken Line)

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 /world in 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
2. Interactive Choice Trigger Syntax (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.
Section 4 // Script Mechanics & Navigation Targets

Built-in script_mechanic Presets, VR Level Slugs & Page Modals

βš™οΈ Physics & Player Buffs
  • 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
βš”οΈ Combat, Crew & Atmosphere
  • 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_Dance party
  • crew_battle_mode β€” Switches Stage Crew to combat stance
  • neon_storm_sky / disco_lights / earthquake_shake
πŸ—ΊοΈ Level Slugs & Page Prefixes
  • 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
Section 5 // Multi-Goal & Kill Counter Engine

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.
Section 6 // Complete Schema Reference

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.