I Want To...

Audience: Plugin authors, content creators · Prereqs: None

A task-oriented index into this wiki - phrased as goals, not page titles. If you already know which page you need, use the sidebar; if you're not sure where something lives, find your goal below and follow the link. Every link points at a page with real, working code, not just prose.

Looking for real code to read, not a guide to follow?

Skip straight to plugins_default/ (first-party plugins bundled with LegacyShell, running in production right now - legacyshellcore, healthpackitem, parkourmode, and friends) or plugins_samples/ (minimal, dedicated teaching examples - sample1cmd, sample2dependency, whose own folder comment says "copy folders into the plugins folder to activate"). Don't look in plugins/ - on a fresh install that folder is empty; it's where your own plugins and third-party installs go, not a source of reference code.

Getting started

...make my first plugin. Quickstart - a working plugin in about ten minutes.
...understand the plugin folder structure and what files are required. Anatomy.
...know what order my plugins (and other people's) load in. Lifecycle.
...make my plugin require another plugin, or an npm package. Dependencies.
...understand the event system (on/emit) that everything else is built on. Events (concept).
...look up the exact payload of a specific event. Event Reference - generated from source, always current.

Reacting to gameplay

...run code when a player dies, joins, fires a weapon, etc. Events (concept), then find the specific event in the Event Reference.
...add a new slash command. Commands.
...reward consecutive kills with a temporary buff. Recipe: Killstreaks.
...give a player in-game currency (eggs). Recipe: Rewarding Players with Currency.
...attach my own custom data to a player. Recipe: Custom Per-Player Data.
...fully replace something core code does by default, not just react to it. Events (concept) - plugins.cancel, then Recipe: Replacing Core Behaviour.

Adding content

...add a new gamemode. Recipe: New Gamemode, background in Gamemodes.
...understand or add gameplay multipliers like speed, gravity, or damage. Modifiers.
...add a theme, or understand how the theming system actually works. Recipe: Custom Theme.
...change how an existing weapon fires, or add a new one. Recipe: Custom Weapon.
...add a new pickup item (health, ammo, a custom power-up). Recipe: New Pickup Item, background in Items and Skins.
...add a new hat, stamp, or weapon skin. Hats and Stamps and Items and Skins, shipped via Content Packs.
...add a new collidable map block, and actually understand how its collision gets generated. Map Blocks - covers the naming convention and exactly where each colliderType's collision geometry comes from.
...build or edit a map. Maps.
...add sound effects or music. Sounds for the assets, Sound and Apollo for triggering them from code.
...add a seasonal/limited-time shop event. Seasonal Events.
...ship models, items, and maps together as one plugin. Content Packs - the pattern legacyshellcore itself uses.

Client-side and UI

...add my own UI element (a HUD element, a menu, an overlay). Recipe: UI Modification.
...ship any JavaScript that needs to run in the browser. Client-Side Code.
...serve my own static assets (textures, extra pages, downloadable files). Static Assets.
...add a new network message/opcode. Networking, reference in Comm Opcodes.
...understand why my server-side change feels delayed, or how to avoid that. Prediction and Authority.

Persistence and external integration

...make my plugin's data survive a server restart. Recipe: Persistent Storage.
...post messages to a Discord webhook. Recipe: Discord Integration.
...know whether my plugin's in-memory state is shared across rooms, or across the main thread. Workers and State - short answer: no, and this explains exactly why.

Publishing and troubleshooting

...share my finished plugin with others. Publishing.
...avoid the mistakes other plugin authors have already made. Pitfalls.
...figure out why my plugin doesn't show up in the boot log, or crashes on load. Anatomy - Common Issues.

Understanding the engine itself

These go deeper than "how do I build X" - they're for when you need to know why the engine behaves a certain way, usually because you're doing something advanced or debugging something subtle. Start at the Codebase Reference index, or jump straight to a common one:

...understand the 60Hz game loop and when full-state syncs happen. Game Loop.
...understand how rooms and worker threads relate to each other. Rooms and Workers.
...understand exactly how map-block collision is generated, at the engine level. Physics and Collision.
...understand the browser build pipeline (how shared code becomes the client bundle). Build Pipeline.
...understand the binary wire protocol itself. Wire Protocol.

This page was drafted with AI assistance and reviewed for accuracy. If something looks wrong, please open a PR or flag it.