# VXLVERSE

> VXLVERSE (https://vxlverse.com) is a free, browser-based 3D game maker. A game is written as a short plain-text script called **VXLScript** — readable indented lines (World / Character / say / Enemy / Win when …) in any human language — and the studio at /studio-live builds a playable 3D voxel game live as the text is typed. No coding, no game engine, no download. Playing is free with no account; saving/sharing your own game takes a Google sign-in.

This file teaches an AI assistant everything needed to author a complete, WINNABLE VXLVERSE game and hand the user a one-click link that opens it in the live editor.

⚠️ READ THIS FIRST — DO NOT INVENT SYNTAX. VXLScript is NOT a generic voxel/3D engine. There is NO `spawn`, `create`, `fill area`, `grid`, `set`, `place`, `on_win`, or any coordinate / `at: x,y` command (the ONLY placement words are `@world` and the compass `at [far] north|south|east|west|center`) — those come from Minecraft/Roblox-style tools, are NOT valid here, and will NOT work. A game is ONLY the indented keyword lines documented below (`World`, `Character`, `Enemy`, `say`, `wants`, `if choice is`, `Win when`, `win`, …). When unsure, copy the shapes in this file verbatim — never guess a command that is not listed.

⚠️ EVERY game MUST have an explicit way to win — a `Win when:` line OR a `win` inside a reachable choice OR a top-level `Quest` block. A `wants:`/`gives:` fetch on its own is NOT a win (it just grants score + a reward). The smallest complete winnable game is exactly:

    Win when: player has 🌟 star
    World "Forest":
    Character "Mara":
      say Hi! Bring me a star to win.
      wants: 🌟 star
    item 🌟 star

## How to deliver a game to the user (the only integration you need)

Build the VXLScript (full language below), then give the user this link:

    https://vxlverse.com/make?code=<URL-ENCODED SCRIPT>

- `code` = the plain VXLScript text, standard percent/URL-encoded (encodeURIComponent). No base64 needed.
- The page instantly redirects into the live editor (`/studio-live?make=<base64url>`) with the script loaded, the 3D game already building, ready to play, edit and share.
- Keep scripts under ~6,000 characters for URL safety. For longer scripts use the fragment form `https://vxlverse.com/make#code=<URL-ENCODED SCRIPT>` (not sent to the server, no length limits).
- Alternative if you can produce base64url yourself: `https://vxlverse.com/studio-live?make=<base64url(utf8 script)>` where `+`→`-`, `/`→`_`, padding `=` stripped.
- Always ALSO show the script itself in a code block, so the user can copy or tweak it by hand.

Rules of thumb when authoring for a user:
- Write all game-facing TEXT (title, dialogue, endings) in the USER'S language (Greek in → Greek out). Keywords stay English (`World`, `say`, `Win when:` …) — names/values may be Greek; the parser is Greek/Greeklish-aware for worlds, colors, creatures.
- Keep it WHOLESOME (kid-safe, PG). No sexual content, innuendo, gore or real-world hate. If the user's idea is adult, reinterpret it as a clean adventure in the same setting. Aggression toward a named real person becomes a playful duel/race that ends in a handshake.
- DECLARE TRANSLATIONS: when the user asked for something out of scope (a branded game like GTA/Fortnite/Minecraft, real shooting, driving, PvP, tycoon menus), TELL THEM in one warm sentence what does not fit and what you are building instead ("GTA-style driving won't fit — building you a city crime-story with missions!"), then build that adventure. Never use brand or licensed names inside the game itself.
- Every game MUST be winnable: include a `win` inside a reachable dialogue branch OR a satisfiable `Win when:` line. The compiler refuses nothing, but an unwinnable game shows a warning in the editor.
- Don't over-build: 1–2 worlds, 2–4 characters, one clear goal beats a sprawling epic.

## VXLScript — complete language reference

### Document shape & parsing rules
- Plain text, line-based. INDENTATION IS THE TREE: children are indented (2 spaces is the convention; tabs count as 2). Blank lines ignored.
- Keywords are CASE-INSENSITIVE. Quotes around names are optional (curly quotes auto-normalized).
- `# whole-line comment` is dropped. A trailing ` # comment` (space before #) is stripped only from structural lines (headers, traits, `Win when:` …). Free text after `say`/`Story:`/`Ending:` keeps a literal `#`.
- Unknown block keyword (e.g. `Charcter`) demotes to narration and SKIPS its whole indented block (a "did you mean" warning fires for near-misses). Any unrecognized indented line under a Character becomes a `say` line.
- THE ONLY HARD ERROR (the game fails to build): `Win when: talked to X` where no Character "X" exists. Everything else degrades to warnings.
- Names slug to ids in any language (Greek keeps Greek letters); gates/wins match items and characters BY NAME, emoji ignored — `if player has 👑 crown:` matches `item 👑 crown`.

### Top-level lines (any order; put them at the top)
    Title: The Lost Crown            # game name (default: "My Adventure")
    Goal: Find the 3 gems            # HUD hint; auto-derived from the win rule if omitted
    Story: The beach was quiet.      # one line of opening narration; stack up to 8 (220 chars each)
    Ending: You saved the island!    # win-screen text (single ending)
    Ending "good": Peace returns.    # NAMED ending — pair with `win good` in a branch (multiple endings)
    Win when: <condition>            # ONE global win rule (last one wins) — see Winning
    Mode: waves                      # game kind: parkour | waves | normal (omit = story) — see Kinds
    Weapon: sword                    # starting weapon: pistol smg shotgun crossbow blaster dagger sword hammer
    Waves: 10                        # wave count for battle mode, 1–50
    Music: fantasy                   # soundtrack mood — see vocabularies

Aliases accepted: `intro`→Story, `outro`/`finale`→Ending, `win if`→Win when, `game type`→Mode, `gun`→Weapon, `rounds`→Waves, `soundtrack`/`song`→Music.

### Worlds (optional; max 6; 2+ worlds auto-connect with portals)
    World "beach":
      music: horror                  # per-world soundtrack override (same 13 moods as Music:)
      Character "Mara":              # anything indented under the World lives there
        say Hello!
- The name free-matches (English/Greek/Greeklish) to one of 19 biomes: beach, dungeon, house, snow, desert, jungle, forest, city-night, city-day, volcano, swamp, canyon, cemetery, mushroom, crystal, autumn, savanna, tundra, badlands. No match → forest. "Spooky Castle" → dungeon, "παραλία" → beach.
- dungeon + house are INDOOR rooms. Dark-themed: cemetery, volcano, city-night, dungeon, house, crystal, mushroom.
- Column-0 `Character`/`Enemy`/`Ally`/`item` lines AFTER a World (not indented) still join that world until the next `World`.
- `in: cave` under a Character moves that one character OUT of the first/default world into the named world. It's ignored on a character already declared under a second-or-later `World` block — indent the character under the World you want instead.

### Characters & dialogue (max 24 characters; the player walks up and presses E)
    Character "Mara":
      say Welcome, traveler!        # a dialogue page; stack up to 12 per node; quotes optional
      say Bring me the lost crown.
- Aliases: `char`, `npc`, `person`, `hero`.
- Looks (all optional, under the Character):
    gender: girl                    # girl|boy|man|woman (or a bare `girl` line); otherwise inferred from dress/Greek name endings
    hair: long blonde               # colors: black brown blonde red grey white blue pink purple green; "long" = long hair
    wears: red shirt                # alias clothes:; a dress/skirt word routes the color to a dress (⇒ female look)
    dress: purple
    pants: navy
    skin: tan                       # pale fair medium olive tan brown dark

### Choices & branching (max 3 options per menu; nestable)
    Character "Guard":
      say Who goes there?
      if choice is "A friend":
        say Pass, friend.
        win
      if choice is "None of your business":
        trust_guard - 1
        say Hmph.
      else:
        say Think about it.

### Gates — condition branches (under a Character)
    if player has key:              # item gate; `if player has 3 gems:` = live count gate
    if talked to "Elder":           # opens after finishing a talk with THAT character (must exist!)
    if talked before:               # second+ conversation with this same character
    if coins >= 10:                 # named counter gate; ops: is/=/==/>=/<=/>/< ("is" means AT LEAST)
    if warmer:  /  if colder:  /  if neutral:   # relationship gates — see Relationships
    if warmer and player has 🎁 gift:           # AND-gate — opens only when EVERY condition holds
    if talked to "Tom" and talked to "Ana":     # combine any conditions with `and` (2+ allowed)
    else:                           # fail branch of the gate directly above (same indent)
- A top-level gate on a character becomes an auto-shown gated greeting; a gate written inside a choice becomes an in-place fork. Wrapping `if choice is` menus inside a gate (`if player has X:` then choices) is fully supported, and mixing gated reactions with a choice menu on one character is clean (no warning).
- `and`-gates: join conditions on one `if … :` line with ` and ` (any mix of player-has / talked-to / warmer / counter). The branch opens only when ALL are true — the way to require several clues, an item AND a mood, etc. (There is no `or`; write separate gates for alternatives.)
- Gate items that can't be obtained are auto-placed on the floor silently (only the `Win when: player has X` auto-placement warns).

### Items, quests & inventory
    item 👑 crown                   # floor pickup in the current world; first emoji = its icon (else keyword-guessed)
    item 🧪 potion heals 30         # usable consumable: restores 30 HP (drink from the bag)
    item 🔋 cells ammo 24           # refills gun ammo (aliases: refills / reloads)
    item 🪙 coin x10                # quantity scatter (max 30 copies)
    item 💎 gem @cave               # place in another world by name
    item 🗺️ map at far north        # compass placement: at [far] north|south|east|west|center (kid words — no coordinates)
    give 🔑 key                     # under a Character: the NPC gifts the item via a "Take the key 🎁" choice
    wants: 🐟 fish                  # under a Character: fetch quest — bring the item to this NPC (one per character)
    gives: 🏅 medal                 # under the SAME Character: the quest reward (needs wants:; one per character)
- Coins/treasure go to the backpack (NOT to score). Delivering a `wants:` quest awards 50 score + the `gives:` item.

### Quest chains (a top-level `Quest` block — ordered steps that auto-track)
    Quest "The Journey":            # a named, multi-step quest shown in the HUD tracker
      talk to Rowan                 # step 1: walk to Character "Rowan" and press E
      get herb                      # step 2: pick up item herb  (aliases: collect / find / bring;  `get herb x2` = 2)
      defeat Warden                 # step 3: kill Enemy "Warden"  (aliases: kill / beat / slay)
- Steps run IN ORDER; the tracker shows the current one ("The Journey — Talk to Rowan (1/4)") and the ◆ marker leads to it. Completing a step auto-advances to the next — no dialogue/Accept needed. Finishing the LAST step WINS the game (so a `Quest` block needs no separate `Win when:`).
- Each step's target must be a declared `Character` (talk), `item` (get), or `Enemy` (defeat). Max 12 steps. The single-line `wants:`/`gives:` fetch quest above still works and is unaffected.
- Step targets match BY NAME with emoji ignored, exactly like gates (`get 🏮 lantern` and `get lantern` both match `item 🏮 lantern`), and a step may target a Character/item/Enemy in ANY world — the ◆ marker leads across portals. A `talk to X` step completes the moment you press E to open the conversation, however many say-lines it has. Use a Quest chain of `get` steps for a "gather several things, then deliver" recipe (a single `wants:` takes only one item).

### Enemies (max 16 types; they attack the player on sight)
    Enemy "Skeleton King":
      kind: skeleton                # skeleton zombie mummy drone dog wolf raider robot slime bat spider ghost wyrm golem
                                    # synonyms map: dragon→wyrm, giant/troll→golem, alien→drone, bear→dog, goblin/orc/pirate/knight→raider,
                                    # ghoul→zombie, vampire→bat, scorpion/bug→spider, phantom/spirit→ghost, ooze→slime
      tier: 10                      # difficulty 1–50 (size/HP/damage scale)
      count: 5                      # spawn exactly N (1–99); any count = exact authored roster
      fights: ranged                # behavior: melee(chase) | swarm | ranged | flanker | support (healer)
      hp: 500                       # overrides: hp 1–5000, speed 1–30, dmg 0–200
      speed: 8
      dmg: 15
      drops 🦴 bone                 # always drops this item on death
- Aliases: `monster`, `foe`, `villain`, `boss` (alias of Enemy — bossness comes from attacks:/phases:, below).
- Omitting `kind:` infers the creature from the name ("Dragon" → wyrm look, "Troll" → golem look).

### Bosses (an Enemy with attack patterns; spawns as the finale)
    Enemy "Dragon Lord":
      attacks: slam volley / charge / summon   # 4 moves: slam volley charge summon; "/" splits HP phases (max 3)
      phases: 3                                # phases alone also makes a boss (default attacks)
- A boss gets a health bar, telegraphed attacks and forced tier 4. In a story with no other win rule, a boss auto-switches the game to a wave battle.
- A wave battle wants at least ONE non-boss enemy too — declare a regular `Enemy` (a few trash mobs) alongside the boss, or a lone-boss battle auto-adds a warm-up wave (the editor shows a note when it does — that note is informational, not an error).

### Allies (companions; squad max 20 per world)
    Ally "Rex":
      kind: dog
      count: 3                      # N numbered copies (Rex 1, Rex 2, …)
- Aliases: `companion`, `friend`, `pet`, `sidekick`. Allies follow the player and fight enemies. Parkour mode removes allies and enemies.
- An Ally declared inside a `World "x":` lives in THAT world only; declare it BEFORE any World line to make a global companion that follows through portals. A top-level Ally can also be pinned to one world with `in: reef` (same as a Character's `in:`). Each world fields up to 20 active companions (globals count everywhere).
- Every world keeps its OWN cast: enemies, NPCs, items and allies you write under (or after) a `World` block only appear in that world, and each world wears its own natural sky/light (a night moon, a bright reef). A boss authored in a later world stays the finale of THAT world — it will not gate-crash another world's last wave.

### Relationships & mood (per-character trust, 0–5, starts at 2)
    Character "Nia":
      if choice is "You look lovely today":
        trust_nia + 1               # raise/lower with counter lines on trust_<slugged name>
        say Oh, thank you!
      if warmer:                    # trust >= 3
        say I trust you now.
        join me                     # the NPC becomes a fighting companion
      if colder:                    # trust <= 1
        turn hostile                # the NPC becomes an enemy
- `trust_*` counters can NOT be a `Win when:` goal.

### Score & counters (fire when the dialogue line is reached)
    score + 10                      # points (win with `Win when: score is 30`)
    coins + 5                       # any named counter; also `coins - 2`
    set coins to 0                  # absolute set; also `coins = 10`
- Reserved words can't be counter names (say, win, give, item, if, score, set, world, character, enemy, loop …).

### Winning & losing
    win                             # inside a branch: instant victory ("The End")
    win good                        # victory showing the named `Ending "good":` text
    lose                            # inside a branch: defeat
    Win when: defeat all            # global rules: defeat all | defeat <Enemy name> | survive
    Win when: player has 👑 crown   #   player has [N] <item> — hold the item, or N of it: `player has 20 🪙 coin` (auto-placed if unobtainable)
    Win when: player has 🥕 carrot and 🧅 onion and 🍄 mushroom   # SET win — hold ALL, any order (recipe / collect-a-set / clues)
    Win when: talked to Mara        #   talked to <Character> — the character MUST exist (hard error!)
    Win when: reach Castle Peak     #   reach <World> — win on entering that world via a portal (needs 2+ worlds; not the START world)
    Win when: survive 300s          #   survive Ns — a live TIMER; win when it elapses ("survive 5 minutes" also works). Bare `survive` = clear the enemies instead.
    Win when: defend Rex for 90s    #   defend <Ally> for Ns — hold out N seconds with that ally alive (its death loses the run)
    Win when: score is 30           #   score is/reaches N   |   <counter> is N
    Lose when: time > 90s           # global LOSS: run out of time — lose once the clock passes N seconds
    Lose when: Rex dies             #   <Ally> dies — an escort/protect fail: lose the run if that companion falls
- ONE `Win when:` per game (the last wins). A `win` inside dialogue overrides an item/talked `Win when:` (warning). `Lose when:` is separate and pairs with any win rule (e.g. `survive 300s` + `time > 90s`, or `defend Rex for 90s` on its own).
- What flips a STORY into a wave battle: ONLY a `Win when: defeat …/survive` (bare) or a declared boss. A Quest `defeat` step, a roaming `Enemy` beside a dialogue `win`, or a `survive 300s`/`defend` timer all STAY a story — the enemies simply roam and threaten (great for escort/survive-the-clock games).
- To win on a QUANTITY of a physical PICKUP (`Win when: player has 20 🪙 coin`) — hold N of that `item` — the count is stripped and matched to the authored item, same as the `if player has 3 gems:` gate. But when the quantity is EARNED as points (kills, choices) rather than picked up off the floor, use a COUNTER instead: add `coins + 1` where each coin is earned, and `Win when: coins is 20`.

### Loops (text macros — expand before parsing; max 30 reps)
    loop 3 as i:
      Enemy "Guard $i":             # $i = 1..3 → Guard 1, Guard 2, Guard 3
        kind: raider
    loop over coin, gem, star as x:
      item 🍀 $x

### Game kinds (Mode)
- (no Mode line) → STORY adventure: explore, talk, quest, win by dialogue/`Win when:`.
- `Mode: waves` → wave BATTLE: fight `Waves: N` (default 5) waves of your enemies, boss last. Synonyms: battle, combat, arena. No enemies declared → a default roster is injected.
- `Mode: parkour` → floating-platform jump course auto-built from the Title; enemies/allies are removed. Synonyms: platformer, jump.
- waves/parkour auto-win by their own rules — no `Win when:` needed.

### Exact vocabularies
- Worlds (22): beach reef moon candy dungeon house snow desert jungle forest city-night city-day volcano swamp canyon cemetery mushroom crystal autumn savanna tundra badlands
- Creature kinds (14): skeleton zombie mummy drone dog wolf raider robot slime bat spider ghost wyrm golem
- Weapons (8): pistol smg shotgun crossbow blaster dagger sword hammer
- Music moods (13): ambient exploration fantasy battle horror mystery town cinematic sad victory scifi jazz_funk menu
- Boss attacks (4): slam volley charge summon — fight roles (5): melee swarm ranged flanker support
- Colors: red blue navy green yellow orange purple pink black white grey brown teal cyan gold maroon (hair also: blonde)

### Hard limits (the parser clamps/culls past these, with warnings)
6 worlds · 24 characters · 16 enemy types · 20 allies total · 12 dialogue pages per node · 3 choices per menu · 12 dialogue nodes per character · 8 Story lines · 220 chars per Story/Ending line · 30 copies per item · loops ≤30 reps & ≤1500 expanded lines · tier 1–50 · waves 1–50 · boss phases ≤3 · hp ≤5000 · speed ≤30 · dmg ≤200

### Common mistakes (avoid these)
1. `Win when: talked to X` without declaring Character "X" → the ONLY fatal error.
2. `gives:` without `wants:` on the same character → demoted to a plain gift.
3. A 4th `if choice is` on one menu → dropped with its whole body. Split across pages instead.
4. Expecting a top-level `win` to work in a populated game → it only fires inside dialogue; use `Win when:` for global rules.
5. Using `trust_x` as a win goal → rejected; use a normal counter.
6. Forgetting that `Mode: parkour` deletes all enemies/allies/quests — parkour is Title + Mode only.
7. Story games don't need combat: don't force enemies into a quiet quest.
8. `Win when: player has N X` (e.g. `player has 20 coin`) requires HOLDING N of that physical `item`. If the "coins" are earned as points (not floor pickups), model them as a counter instead: `coins + 1` + `Win when: coins is 20`.
9. Every game needs an explicit win: a `Win when:`, a `win` in a reachable choice, or a top-level `Quest` block. A lone `wants:` is NOT a win.

## Worked examples (each is a complete, winnable game)

### 1 · Story adventure (quest, gift, multiple endings)
    Title: The Lighthouse Secret
    Story: The light went out last night. The fishing boats are lost in the fog.
    Ending "hero": The light burns again. The boats come home. ⛵
    Ending "quiet": You kept the secret. The sea keeps its ghosts.

    World "beach":
      Character "Old Keeper":
        say The lamp wants its 💎 sun-crystal back.
        wants: 💎 sun-crystal
        gives: 🗝️ brass key
        if talked before:
          say Check the cave, past the rocks.
      item 💎 sun-crystal @cave

    World "cave":
      Character "Echo":
        say Some lights are better left dark…
        if choice is "Relight the lamp":
          win hero
        if choice is "Let the sea rest":
          win quiet

### 2 · Wave battle (boss, roles, weapon)
    Title: Last Stand at the Canyon
    Mode: waves
    Waves: 6
    Weapon: crossbow
    World "canyon":
    Enemy "Raider":
      kind: raider
      fights: melee
    Enemy "Sharpshooter":
      kind: drone
      fights: ranged
      tier: 8
    Enemy "Warlord":
      attacks: slam volley / charge / summon
      phases: 3
    Ally "Scout":
      kind: dog

### 3 · Parkour course (the Title shapes the course)
    Title: Cloud Kingdom Dash
    Mode: parkour
    World "snow":

## Links
- Studio (live editor): https://vxlverse.com/studio-live
- Open-a-script deep link: https://vxlverse.com/make?code=<url-encoded VXLScript>
- Human guide (same language, illustrated): https://vxlverse.com/guide
- Play ready games: https://vxlverse.com/games · Community games: https://vxlverse.com/explore
- X/Twitter: https://x.com/strugglecoder · YouTube: https://www.youtube.com/@theStruggleCoder