Jamango Built-In Template Traits

Source for a Jamango world: gameplay traits and the systems that implement them.

Getting started

There are two ways to use these traits:

1. Start from a template world — the built-in template worlds on jamango.io already ship with these traits as a base. Pick one and start building.
2. Bring them into your own world — use Local Sync to connect this repo to any world, including an empty one with no traits yet. Instructions below.

Bring these traits into an existing world

This uses Local Sync, the same folder-sync workflow most active creators already use. We recently upgraded the Local Sync client; it's easier to set up and pulls the latest context files automatically.

1. Get this repo onto your machine — either way works:

   • Download it (no git needed): click the green Code button at the top of this page, choose Download ZIP (direct link), then unzip it somewhere easy to find, like your Desktop or Documents folder.
   • Clone it with git (if you have git installed and want easy updates later):

     git clone https://github.com/JamangoGame/template.git
     

2. On jamango.io, open the world you want to add the traits to (a new, empty world is fine).

3. Press J to open the in-game script editor.

4. Click Connect folder.

5. For the initial sync direction, choose Folder → Browser. This pushes the template's traits up into your world. Then select the folder you downloaded or cloned in step 1 (if you downloaded the ZIP, pick the unzipped folder).

   ⚠️ Direction matters. Folder → Browser makes your local folder the source of truth and imports its traits into the world. Choosing Browser → Folder instead would treat the world as the source of truth and could overwrite your local files — only use that direction when syncing into a fresh, empty folder.

6. The traits load into your world, and the sync is established. Any local changes — whether you edit files yourself or have Claude Code or another tool edit them — now update your game on Jamango automatically.

Project structure

• src/client.ts, src/server.ts: entry points; behavior lives in the systems modules.
• src/config.ts: default player movement settings.
• src/traits/index.ts: trait definitions (schema and editor metadata) and DEFAULT_TIME_LEADERBOARD.
• src/shared/commands.ts: network commands.
• src/shared/utils.ts: vector, quaternion, and format helpers, plus setEntityHidden.
• src/shared/vehicle.ts: vehicle trait, commands, and raycast vehicle physics.
• src/shared/debug.ts: debug draw stubs (no ops).
• src/client/systems.ts: HUD, dialogue, nameplates, motion visuals, NPC animation, held items, music, death animation, visibility.
• src/client/hud-kit.ts: HUD helpers (panels built once, textContent caches, toast, world interact prompt).
• src/client/vehicle-ui.ts: vehicle enter and exit hints.
• src/server/systems.ts: spawning, checkpoints, respawn, timers, collectables and gates, signals and chains, platforms, impulses, gravity areas, projectiles, zombies, NPC look at, avatars, dialogue and notifications.

Traits

Names are the editor labels; id is the string passed to J.defineTrait.

Players and spawning

• Player (player): Player marker, applied automatically; holds score.
• Player Permissions (playerPermissions): Default permissions (interact, fly, force respawn, individual blocks).
• Spawn (spawn): Spawn point; highest priority enabled wins.
• Checkpoint (checkpoint): Updates a player's respawn point on touch.

Hazards

• Death On Collide (deathOnCollide): Respawns players who touch it. Optional delay, reset, sound, signal.
• Projectile Spawner (projectileSpawner): Fires a prop projectile on a cadence. Optional kill on hit.

Signals and logic

• Enable By Signal (enableBySignal): Gates and hides an entity until a signal toggles, enables, disables, or holds it active while a pad is occupied.
• Send Signal On Collision (signalSendOnCollision): Emits a signal on collision start, end, or while colliding (a pressure pad).
• Chain (chain): A trigger (game start, interact, collision, signal) runs an action (emit signal, remove self).
• Play Animation On Signal (playAnimationOnSignal): Plays a character animation when a signal fires.

Motion, platforms, and forces

• Bobbing (bobbing): Looping motion along any axis.
• Spinning (spinning): Steady rotation.
• Moving Platform (movingPlatform): Kinematic platform between two points, with ping pong and wait.
• Disappearing Platform (disappearingPlatform): Hides shortly after contact, then respawns.
• Velocity Impulse (velocityImpulse): Sets or adds velocity on contact.
• Gravity Area (gravityArea): Changes gravity inside the area.

Timers, collectables, and leaderboards

• Timer Start (timerStart): Starts a player timer on touch.
• Timer Finish (timerFinish): Stops the timer and can submit it to a leaderboard.
• Collectable (collectable): Scored collectable (value, group, remove, hide, or respawn).
• Collectable Gate (collectableArea): Emits a signal once a player has collected enough.
• Counter HUD (counterHUD): Cached HUD counter for collectables, score, or timer.
• Leaderboard (leaderboard): Displays a leaderboard on the HUD, as world text, or both.
• Leaderboard Settings (leaderboardSettings): Declares a leaderboard (id plus lowest or highest mode).

Default time leaderboard id: template_best_times_v1 (lowest wins).

Notifications, sound, and music

• Display Notification (displayNotification): Toast on game start, collision, or interact.
• Play Sound On Collision (playSoundOnCollision): Plays a sound on touch.
• BGM Playlist (bgmPlaylist): Looping background music with shuffle, volume, fade.

NPCs, avatars, and held items

• NPC Name (npcName): Character nameplate.
• Dialogue NPC (dialogueNPC): Interactable dialogue with optional talk animation and sound.
• NPC Animation Loop (npcAnimationLoop): Plays an animation clip (once, loop, hold).
• NPC Look At Nearest Player (npcLookAtNearestPlayer): Throttled look toward the nearest player in range.
• Zombie (zombie): Chaser with pathfinding and attack range, plus optional zombie avatar.
• Avatar Override (avatarOverride): Overrides avatar colors, face, animations, or components.
• Held Item (heldItem): Item or prop held in a character's slot, with a hold pose.

Vehicles

• Vehicle (vehicle): Drivable vehicle prop with configurable wheels. Right click to enter, crouch to exit.

Runtime traits

Managed by the systems, no editor UI: playerCheckpoint, playerTimer, playerCollectables, visibility, playerVehicleMount.

Examples

Pressure pad

Enable something while a player stands on a pad and disable it when they leave, using two traits:

1. On the pad prop, Send Signal On Collision: Send on = While colliding, Signal = pad1, Collides with = Player.
2. On the object to gate, Enable By Signal: Signal = pad1, Mode = Hold while colliding, Starts enabled = off.

The pad emits while it is occupied and the gate mirrors that, so the object is shown with physics on only while someone is on the pad. It stays on while any player is on the same pad and releases when the last one leaves.

Reference

• node_modules/jamango/api.ts: API reference
• node_modules/jamango/README.md: patterns and UI guide
• node_modules/jamango/HUD-PATTERN.md: always visible UI pattern
• node_modules/jamango/assets.ts: asset IDs for this world
• CLAUDE.md and AGENTS.md: project rules (identical content)