**IMAGE** IMAGE Matrix Action Game Engine *User Guide • v1.0 Core* By Spax Orion & Dirty Helga • Ozone MiniVerse http://xoaox.de:7000 *OpenSim 0.9.2.1 (Yeti) / Mono / XEngine / BulletSim / OSSL* **0. Original Plan** It was initially intended that this release come out as a Tutorial. Upon completing this assembly, it was determined that the process for building this game from scratch would be maddening. Since this is a modular framework, it was decided that IMAGE will ship as a 1.0 RELEASE and owners can upgrade it with new modules that appear here (or in-world) over time. People who can follow instructions will get a fully working framework to power their games, the lazy get NOTHING. This documentation and THE SCRIPTS are the TUTORIAL. **1. What IMAGE Is** IMAGE is a modular action game engine for OpenSim. Drop in the root prim, configure a handful of variables, and you have a working NPC-combat experience with scoring, music, attract mode, and weapon deployment --- with no external game server required. The minimum working installation is three prims: the root controller, a scoreboard child, and a weapon-hook child. Everything else is optional. **2. Prim Structure** All prims below are linked into one linkset. The root prim carries the core game script; child prims are identified by name. ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **Prim / Folder** **Script** **Purpose** ---------------------------------- ---------------------------------------------------------------- ------------------------------------------------------------------------- Root prim !.IMAGE-Core-Game-v1.0.4.lsl NPC AI, game modes, audio, attract loop ga-score (child) !.IMAGE-Module-KillBoard.lsl + !.IMAGE-Module-KB-EE.lsl Live scoreboard rendered to face 2; persists scores to notecard gun-disp (child) ..IMAGE-Module-WeaponHook..lsl Touch → stage player → rez SlugShooter weapon attract (child) ..IMAGE-Module-AttractSign.lsl Broken-neon texture flicker effect; cosmetic only SlugShooter (object in gun-disp) !.IMAGE-Module-TempGUN-v1.0.3.lsl + !.IMAGE-Module-CastRAY.lsl Invisible follower gun; mouselook LMB fires raycast slugs slug (object in SlugShooter) ..IMAGE-Module-VTracer.lsl Visible tracer projectile; reports hits back to controller orbitSR (object in gun-disp) !,IMAGE-Module-OrbitSR.lsl Audio relay object that follows the player; plays weapon SFX regionally ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **⚠** *ArenaDROP --- a phantom child prim you name exactly \"ArenaDROP\" --- sets the attract-mode show center. Without it the script falls back to ArenaDropFallback coords in the config.* **3. Game Modes** Touch the root prim from inside the arena to get the mode dialog. Spectator-zone and out-of-arena players are blocked from starting a game. --------------------- ----------------------------------------------------------------- **FAMINE** 2 Grugs · 3-minute timed match · Famine music track **HUNGER** 3 Grugs · 5-minute timed match · Hunger music track **FEAST** 5 Grugs · Endless · Feast music track · ends when arena empties --------------------- ----------------------------------------------------------------- In every mode, killed Grugs respawn immediately near the current target. Timed modes give a 30-second warning. FEAST ends via osGetAvatarList() scan, not sensor range, so it catches the last player even at the arena edge. **4. Attract Mode** When no game is running and a player has been idle near the arena for ATTRACT_IDLE_SEC (default 40 s), the engine spawns ATTRACT_SHOW_COUNT Grugs (default 5) in a rotating ring around ArenaDROP. They dance to Attract music. The moment a non-spectator combatant enters the arena the show stops and the system arms a cooldown. - Attract will not re-arm during the cooldown period (3 × ATTRACT_IDLE_SEC after any stop). - ExpoFlareSignal() is broadcast on EXPO_CH when any active mode starts or stops --- hook an external effects prim to channel -777777 with START / STOP messages. **5. Player Flow** The intended player path is linear and self-contained: -------------------------- --------------------------------------------------------------------------- **1. Enter arena** Player walks into the ArenaNE / ArenaSW bounding rectangle. **2. Touch gun-disp** WeaponHook teleports player to STAGING_POS (permissions-safe dead zone). **3. Accept perms** SlugShooter requests CONTROL_ML_LBUTTON + camera. Must be accepted. **4. Confirm weapon** Fire once in mouselook (LMB) --- slug tracer confirms the weapon is live. **5. Touch root prim** Choose FAMINE / HUNGER / FEAST from the dialog menu. **6. Fight** Grugs chase and bite. Player shoots Grugs. Scoreboard updates live. **7. Teleport on death** Low-health bite teleports player to LandingPoint; health restored to 100. -------------------------- --------------------------------------------------------------------------- **⚠** *Spectators are safe: the spectator bounding box (ArenaSpectatorNE / ArenaSpectatorSW) prevents Grugchase and blocks game launches from that zone.* **6. Scoring** Kill events are sent from the core via llMessageLinked on SCORE_MSG_NUM (9001) to the ga-score child prim. Two message types: ---------------------- ------------------------------------------------------------------------------------------------------------------- **KILL\|uuid\|name** Player killed a Grug. Adds 1 point to that player\'s score. **GRUG\|points** Grug bit a low-health player to death. Grugs earn 3--5 points (random) because clever humans are harder to catch. ---------------------- ------------------------------------------------------------------------------------------------------------------- Kill attribution uses a 10-second window: the last shooter to land a slug hit on a Grug gets credit when that Grug dies. Scores persist to the \"scores\" notecard in the ga-score prim so they survive sim restarts. The scoreboard renders to face 1, cylinder (4 times for reading from any direction) using OSSL dynamic texture drawing (DejaVu Sans Mono, 512×512). Top-5 players plus Grugs total are shown. Touch Scoreboard for DM of ALL scores. **7. Audio** IMAGE supports an external IASR (In-Arena Sound Relay) on channel CH_IASR_CMD (-733102). Set USE_IASR = TRUE (default) and all music loops and one-shot triggers are broadcast to IASR rather than played locally on the board, which prevents double-audio across the region. --------------------- ------------------------------------------------- **LOOP\|name\|vol** Begin looping a named sound asset. **TRIG\|name\|vol** Trigger a one-shot sound. **STOP** Stop any looping sound. --------------------- ------------------------------------------------- Set IASR_LOCAL = TRUE if you also want the board to play sounds locally (risk: double audio on the same client). The orbitSR object follows each player and plays weapon SFX at their position via regionSay on CH_IASR_CMD. **8. Weapon: SlugShooter** SlugShooter is an invisible prim rezzed by the WeaponHook. It attaches to the player via follow-physics on a short timer (0.15 s tick). Key behavior: - Follows at FOLLOW_OFFSET_LOCAL --- chin-height, slightly forward. - Left mouse button in mouselook fires. Respects REPEAT_DELAY (0.35 s default). - CastRAY module performs the actual raycast hit detection using osCauseDamage on detected NPCs. - Hit report sent to controller: HIT\|shooterKey\|victimNpcKey on CH_CAGE_HIT (-733101). - Slug tracer prim (VTracer) is rezzed as a visible effect; it self-deletes after a short life. - INIT_MAX_DIST (64 m default) limits weapon acceptance to players within range of the rezzer. **⚠** *GunFire sound must exist in SlugShooter\'s inventory or in IASR inventory. The script does not crash without it but you\'ll have silent shooting.* **9. Key Configuration Variables** All variables live at the top of each script in the CONFIGURATION section. The most common ones to change on first setup: ---------------------------------------------------------------------------------------------------------------------------------------- **Variable** **Default** **What to set** ----------------------- ------------------- -------------------------------------------------------------------------------------------- LandingPoint \<38, 128, 3010\> Your sim\'s respawn / exit point. ArenaNE / ArenaSW (site-specific) Rectangle that defines the combat zone. Both must be non-zero to activate bounds checking. ArenaSpectatorNE / SW (site-specific) Safe-watch zone. Grugs won\'t chase here. ArenaDropFallback (site-specific) Fallback center for attract ring if ArenaDROP prim is absent. STAGING_POS (gun-disp script) Where players teleport to accept weapon permissions. ATTRACT_IDLE_SEC 40 Seconds of arena presence before attract show starts. GRUG_SPACING 4.0 m Minimum separation Grugs try to maintain between each other. GRUG_RING_RADIUS 2.8 m How close Grugs orbit around their prey. BITE_DAMAGE 10.0 HP removed per Grug bite. NPC_DEATH_POINTS 1 Number of damage events before a Grug dies. Raise for tankier Grugs. ---------------------------------------------------------------------------------------------------------------------------------------- **10. Required Inventory** **Root prim** - Script: !.IMAGE-Core-Game-v1.0.4.lsl - Notecard: .grug (NPC appearance definition for osNpcCreate) - Sounds: Alarm, Growl, Die1, Die2, Famine, Hunger, Feast, Attract - Animations: a.die, a.walk, a.idle, a.dance **ga-score child prim** - Scripts: !.IMAGE-Module-KillBoard.lsl + !.IMAGE-Module-KB-EE.lsl - Notecard: scores (starts empty; engine writes to it) **gun-disp child prim** - Script: ..IMAGE-Module-WeaponHook..lsl - Object: SlugShooter (contains its own script, CastRAY, slug object, zap.ogg) - Object: orbitSR (contains OrbitSR script + audio assets) **attract child prim (optional)** - Script: ..IMAGE-Module-AttractSign.lsl **⚠** *Prim names must match exactly: \"ga-score\", \"gun-disp\", \"ArenaDROP\" --- the scripts resolve child links by name at runtime.* **11. Channels Reference** --------------------------- ------------------------------------------------------------------------------- **-733102 (CH_IASR_CMD)** Audio relay commands to IASR / orbitSR. Must match across all scripts. **-733101 (CH_CAGE_HIT)** Slug hit reports → root controller. Must match SlugShooter and root. **-777777 (EXPO_CH)** ExpoFlare start/stop broadcast to optional external effects prim. **gDialogChan (dynamic)** Player menu channel, computed from root prim position. Private per-placement. --------------------------- ------------------------------------------------------------------------------- **12. Quickstart Checklist** --------------------------- ------------------------------------------------------------------------------- **□ Set coords** LandingPoint, ArenaNE/SW, ArenaSpectatorNE/SW, ArenaDropFallback, STAGING_POS **□ Name child prims** ga-score · gun-disp · (optional) attract · (optional) ArenaDROP phantom prim **□ Load .grug notecard** Must match a valid NPC appearance saved to sim **□ Verify sounds** Alarm, Growl, Die1, Die2, Famine, Hunger, Feast, Attract in root inventory **□ Verify animations** a.die · a.walk · a.idle · a.dance in root inventory **□ Check channels** CH_IASR_CMD and CH_CAGE_HIT match across all scripts **□ Test weapon** Touch gun-disp → accept perms → fire in mouselook → confirm HIT chat **□ Test scoring** Kill a Grug → scoreboard should update face 2 of ga-score prim **□ Test attract** Stand near arena, wait ATTRACT_IDLE_SEC, Grugs should appear dancing --------------------------- ------------------------------------------------------------------------------- *The scripts are the documentation. Read them. They are written to be read.* CC BY-NC • Ozone MiniVerse • Please leave attribution intact.