groupsCommunity
Sandbox: Full codebase architecture — systems, player components, weapons, tools, NPCs
Sandbox Codebase Architecture Overview
The Facepunch Sandbox game is a large reference implementation. Here's a map of the major systems and how they connect.
Core systems
| System | Class | Type | Description |
|---|---|---|---|
| Game loop | GameManager | GameObjectSystem | Player spawning, NPC death, water, achievements |
| Undo | UndoSystem | GameObjectSystem | Per-player undo stacks (128 steps max) |
| Limits | LimitsSystem | GameObjectSystem | Per-player prop/constraint/tool limits via ConVars |
| Cleanup | CleanupSystem | GameObjectSystem | Scene cleanup, per-player cleanup |
| Save/Load | SaveSystem | GameObjectSystem | Scene diff save/load with versioning |
| Control | ControlSystem | GameObjectSystem | Drives IPlayerControllable on contraptions |
| Camera noise | CameraNoiseSystem | GameObjectSystem | Screen shake, punch, recoil |
| Ban | BanSystem | GameObjectSystem | Persistent ban list |
| FreeCam | FreeCamGameObjectSystem | GameObjectSystem | Spectator free camera |
Player components (all on the player prefab)
- Player — health, damage, ragdoll, death
- PlayerInventory — weapon slots, pickup/drop
- PlayerLoadout — loadout persistence and presets
- PlayerData — stats, kills, SteamId
- PlayerFlashlight — flashlight toggle
- PlayerFallDamage — fall damage calculation
- PlayerObserver — spectator camera after death
Weapon hierarchy
CODE
BaseCarryable
└── BaseWeapon (ammo, reload, shoot delay)
├── BaseBulletWeapon (hitscan, BulletConfiguration)
│ └── IronSightsWeapon (ADS)
└── MeleeWeapon (swing, hit detection)Tool Gun architecture
CODE
Toolgun (ScreenWeapon)
└── ToolMode components (one per tool, only one enabled at a time)
├── BaseConstraintToolMode (two-stage selection)
│ ├── Weld, Rope, BallSocket, Elastic, NoCollide
│ ├── Slider, Hydraulic
│ └── KeepUpright
├── Duplicator (copy/paste contraptions)
├── ThrusterTool, WheelTool, HoverballTool
├── StackerTool, LinkerTool, DecalTool
└── Remover, Mass, Resizer, Trail, Balloon, EmitterSpawner hierarchy
CODE
ISpawner
├── PropSpawner (cloud model ident)
├── EntitySpawner (scripted entity prefab)
├── DuplicatorSpawner (JSON contraption)
└── MountSpawner (mounted content)NPC architecture
CODE
Npc (base component)
├── Layers (continuous behaviours)
│ ├── NavigationLayer (NavMeshAgent)
│ ├── SensesLayer (scan for targets)
│ ├── AnimationLayer (anim graph)
│ └── SpeechLayer (subtitles)
└── Schedules (discrete task sequences)
└── Tasks (MoveTo, LookAt, Say, Wait, FireWeapon, PickUpProp, DropProp)Key event interfaces
- Global.IPlayerEvents — scene-wide player events (spawn, death, damage)
- Local.IPlayerEvents — per-player events (camera, inventory)
- Global.ISpawnEvents — intercept spawning (OnSpawn, OnPostSpawn)
- IToolActionEvents — intercept tool actions (OnToolAction, OnPostToolAction)
- Global.ISaveEvents — save/load lifecycle
- ICleanupEvents — cleanup notifications
- IPhysgunEvent — intercept physgun grabs
- IToolgunEvent — intercept toolgun selections
- ICameraSetup — camera effect pipeline (PreSetup, Setup, PostSetup)
Was this helpful?