Installation & Configure

0R Scene Director#

1. Feature overview#

2. Requirements & compatibility#

Hard dependencies (must be started before this resource):

Optional integrations (auto-detected at runtime; nothing breaks without them):

Database: MySQL and MariaDB are both supported; the schema avoids reserved words (e.g. the lights table uses range_m) and is created/migrated automatically.

OneSync is required (entities are spawned server-side and networked).

3. Installation#

1. Drop the resource in your resources directory (e.g. resources/[standalone]/0r-scenedirector).

2. Make sure the start order is:

   cfgCopy

   ensure oxmysql
   ensure ox_lib
   ensure 0r-scenedirector
   

3. Database — two options, pick either:

   • Automatic (recommended): on first start the resource creates all of its tables itself and prints created N table(s). On later updates it migrates missing columns/indexes automatically (migrated: ... lines). The DB user needs CREATE and ALTER rights; if a migration step fails you will see migration failed – … and the resource runs degraded.
   • Manual: import the bundled scenedirector.sql (same schema, CREATE TABLE IF NOT EXISTS — idempotent, safe to run over an existing database). Useful when the game-server DB user is not allowed DDL.

4. Grant yourself access (next section), then in game type /director or press F6.

Updating: when an update adds new files, run refresh then restart 0r-scenedirector. A bare restart does not pick up files that were not in the previous manifest, and the resource will warn: not loaded: <file> – running on reduced fallbacks. Run "refresh" then "restart".

4. Permissions#

Access is decided server-side on every request, in this order:

1. ACE command.director (follows Config.command, so renaming the command renames the ACE), or
2. ACE fallback group.admin, or
3. Framework admin (only if ServerConfig.permission.useFrameworkAdmin = true):
   • ESX: group admin, superadmin or mod
   • QBCore: permission admin or god
   • Qbox: ACE group.admin, group.god or qbx.admin

Typical standalone setup in server.cfg:

add_principal identifier.fivem:1234567 group.admin

Denied attempts are rate-limit logged to 0r_sd_logs (one entry per 30 s per player).

All settings live in config/server.lua → ServerConfig.permission.

5. Opening the editor#

Opening the editor detaches you into a freecam (speed/FOV configurable under Config.camera), hides your ped, and shows the NUI dock with ten tabs. Closing it lands your ped safely (ground snap + a few seconds of ragdoll protection) and restores godmode state.

6. Core concepts: scene, load, play#

• A scene is a named database row owning actors, props/vehicles, replays, FX and lights.
• Load opens exactly one scene in the editor for you: its objects spawn locally around you for editing. Loading is exclusive — the moment you load a scene, every currently playing scene on the server is stopped (a toast tells you how many) and only your loaded scene remains.
• Play starts a scene for everyone: the server spawns all of its entities as networked objects, runs the countdown, schedules per-object delays, plays replays, fires FX and lights. Any number of scenes can play at the same time.
• A playing scene is persistent: it is flagged in the database and, if the server restarts, it is resumed automatically on boot (no countdown, no notifications, spawned into the shared world) and keeps running until someone stops it or loads a scene.
• Test (inside the editor) is a local-only rehearsal that never touches other players.

7. Tab guide#

7.1 Scenes#

• Create — name a new empty scene and start composing.
• Load / Unload — open a scene in the editor (see exclusivity above) or close it.
• Play / Stop — server-wide playback toggle per scene. The list marks which scenes are currently playing (server-authoritative).
• Countdown — an inline seconds field on the loaded scene card (0–10 s, saved as you type). Playback broadcast (entities, FX, lights, replays) begins after the countdown.
• Delays — every actor, prop, replay, FX and light has its own start delay (0–60 s, quick presets 0/0.5/1/2/3/5 s) so a scene unfolds over time.
• Delete / Restore — deletion is a soft delete; a deleted scene can be restored for about five minutes before a background sweep permanently purges it together with all of its actors, entities, replays, FX and lights.
• Rename, actor/object counters, saved badge, and a play-state badge round out each card.

7.2 Actors#

• Place actors with a ghost preview (LMB commit, X cancel). Placement respects the actor cap (Config.composer.maxActors, default 100 per scene).
• Appearance — dress an actor in the clothing editor (illenium-appearance when present, native otherwise) or apply a saved ped from your wardrobe.
• Animation — pick from the built-in catalogue (2 600+ animations in five categories, searchable, with live preview before applying).
• Weapon — give any catalogued weapon (with UI icons).
• Attach — one distance-sorted scroll menu lists every nearby target twice-tagged: carname (replay) and carname (native). Attaching to a vehicle seats/poses the actor on that scene vehicle; attaching to a replay rides the actor on the replay ghost. Selecting the actor later shows its current attachment highlighted; None detaches.
• Move with the gizmo; DEL deletes the selected actor. Deleting a vehicle or replay also deletes every actor attached to it.

7.3 Peds#

A persistent wardrobe: save any dressed ped (model, full appearance, loadout) under a name, organise entries into folders, and reuse them from the Actors tab, the Library caster and replays. Stored in 0r_sd_peds / 0r_sd_ped_folders.

7.4 Replay#

Record real driving/walking and replay it inside scenes.

• Record — press J (Config.recordKey) to start/stop. A soft-glow screen overlay (no text) shows you are recording. Sampling is ~30 fps (sampleMs = 33), limited to 5 minutes / 6 000 frames.
• Save — the buffer uploads in chunks and becomes a replay row (max 50 per scene). If the recorded vehicle had actors attached to it, they are copied into the replay automatically (respecting the actor cap; a toast reports how many were carried or skipped). Each carried rider:
  • spawns exactly where it will ride (replay origin ⊕ attach offset — no visual jump between rest and playback),
  • is a normal selectable actor: click it, move it with the gizmo, change its look/animation, delete it,
  • is displayed by one single ped in the editor (at rest it stands frozen on the car; during preview/rehearsal the same ped rides the ghost — same face, no duplicates, no trailing).
• Preview — a frozen ghost shows the replay's first frame while editing.
• Play/rehearse — play a single replay in the editor at 0.25× / 0.5× / 1× / 2×, or let scene playback trigger it (with its start delay).
• Manage — rename, enable/disable (disabled replays are skipped by scene playback and hide their preview), delete (cascades to its attached actors).

7.5 Spooner#

Freecam world editing while a scene is loaded:

• Props / Peds / Vehicles — searchable, categorised catalogues (with your own additions via Config.customProps / Config.customVehicles), favourites and recents, ghost placement with Q/E rotate and PgUp/PgDn height (hold Shift for coarse steps).
• Snapping — grid (step 0.5), surface and angle (15°) toggles.
• Placed — one list of everything in the scene: props, vehicles, peds, FX and lights, each with select/teleport/delete actions and per-object delay editing.
• Object cap per scene: Config.spooner.maxEntities (default 300).
• Undo for placement mistakes, copy/paste of objects with their properties.

7.6 FX#

• Catalogue — 15 presets in 4 chip-filtered categories:
  • Fireworks: starburst, shot burst, trail burst, fountain
  • Fire & smoke: campfire, large fire, thick smoke, thin smoke
  • Atmosphere: ground fog, dust cloud, sparks, steam
  • Explosion: small, large, molotov
• Placement — click Add, an outlined translucent ghost follows your cursor on the ground (auto ground-lift so nothing spawns buried); LMB commits, X cancels, Q/E rotates, PgUp/PgDn adjusts height.
• Per effect: scale (0.2–5×), start delay, and a repeat interval — continuous presets burn steadily, one-shot presets re-fire every N seconds when a repeat is set.
• Markers — in the editor every placed effect shows a small X marker you can click to select, drag with the gizmo (position saves on release) and DEL to delete. Cap: 60 effects per scene.

7.7 Lights#

• Colour picker — a square saturation/value field with a hue bar underneath (drag anywhere), a glowing live swatch with the RGB readout, and Range (1–100 m) / Intensity (0.5–20) sliders beside it. The whole panel fits without scrolling; Place light sits directly under the sliders.
• Placement — the actual light renders live at your cursor together with a ghost X marker, ground is detected automatically (groundLift keeps it above the surface), LMB commits at the exact spot, PgUp/PgDn adjusts height, X cancels.
• Editing — every placed light shows a clickable X marker in the editor (click the marker or near it — selection has a proximity fallback). The light follows the marker in real time while you drag the gizmo and the position persists when you release or deselect. With a light selected, moving the colour/range/intensity controls edits it live. DEL deletes it from anywhere.
• Playback — the markers exist only in the editor. The instant you press Play they disappear and only the light itself remains, for all players. Cap: 40 lights per scene (server-enforced, like every clamp: RGB 0–255, range, intensity and delay are all validated server-side).

7.8 Vehicle#

Select any scene vehicle and open the mod studio: performance mods, wheel types, primary/secondary/pearlescent colours, palettes, neon (colour + per-side toggles), xenon, turbo and toggles, extras and liveries. Everything is stored with the vehicle and re-applied on every load and play.

7.9 Environment#

Crowd system for living backgrounds:

• Formations: circle, line, grid. Count 1–60, radius 1–30 m, spacing multiplier, male/female mix 0–100 %.
• Presets (11): cheer, party, drinking, hangout, three club variants, hiphop, strip, mixed, idle — each a curated animation pool.
• NPCs are built in batches, ground-probed so nobody floats, and can be converted into permanent scene actors.
• Ambient suppression: with 12+ crowd NPCs the script suppresses vanilla ambient peds/vehicles around the set so your composition stays clean.
• Slow motion: cycle 100 % → 60 % → 40 % → 20 % time scale with Z while directing.

7.10 Library#

1 400+ prebuilt scene presets (multi-actor poses and compositions) in a searchable, categorised browser with favourites. Pick a preset, choose which roles to include, cast each role either with a stock model or any saved ped from your wardrobe, then place the whole group with one ghost. Groups stay linked (group select/loop controls) and can be re-cast later.

7.11 Chase#

Spawns and directs police pursuit against a target vehicle:

• 1–5 units (Config.chase.maxUnits) plus an optional helicopter with its own height/speed/orbit parameters.
• Five styles, freely switchable mid-chase: normal, aggressive, ram, follow, escort — each a tuned driving-style/mission/speed profile in the config.
• Stall detection re-tasks units that get stuck; everything cleans up on stop.

7.12 Cutscene#

Browse the full story cutscene catalogue (with category chips and a character-count badge per entry), pick a cutscene, optionally replace playable roles with other characters, and play it in place.

8. Controls & keybinds#

9. Multiplayer visibility model#

• While editing (scene loaded): your working copy is local — other players do not see your half-built set, your FX previews or your light markers.
• When a scene plays: the server spawns every prop/vehicle/actor as a networked entity and broadcasts the FX and light lists to all clients after the countdown, each client rendering them locally (distance-culled). Everybody sees the same show.
• Late joiners: a player who connects while scenes are playing automatically receives the active FX and lights, so they see the full picture too.
• Stop/kill: stopping a scene tears everything down for everyone, including FX and lights, immediately.

10. Persistence & lifecycle#

11. Database schema#

All tables are prefixed 0r_sd_ and created/migrated automatically (utf8mb4).

12. Configuration reference#

Everything user-tunable lives in config/shared.lua (commented) and config/server.lua. Highlights:

Every numeric input from the UI is re-clamped on the server — client tampering cannot exceed caps.

13. Locales#

• locales/en.json and locales/tr.json ship complete and key-for-key identical (700+ strings each).
• Set the language with Config.locale.
• To add a language, copy en.json, translate the values, keep the keys, and set Config.locale to the new file name. Placeholders like {1} must be preserved.

14. Framework bridge#

All framework contact goes through bridge/ — the core never talks to a framework directly.

Appearance (bridge/appearance/) prefers illenium-appearance and falls back to a native editor. Vehicle keys (bridge/vehiclekeys.lua) auto-detects the key resource or calls your custom export. The bridge folder ships unencrypted so you can adapt it to a custom framework.

15. Customization surface (escrow)#

In escrow builds these stay open and editable:

• config/ — every gameplay/UI/permission setting
• bridge/ — framework, appearance and vehicle-key integration
• locales/ — all UI text
• html/ — the complete NUI (markup, styles, scripts, data catalogues, fonts, images)

The protected part is the core Lua logic under client/, server/ and shared/. Prefer configuring and bridging over asking for core changes.

16. Performance notes#

• Lights and FX are distance-culled per client (a light renders only within range + 60 m); idle render threads sleep at 250 ms.
• Crowd NPCs build in small batches and ambient suppression prevents double-population around big sets.
• Replay frames upload in chunks; playback interpolates between samples, so the 33 ms sampling stays smooth at any fps.
• The 15 s reconciler and all watchers stand down while you are interacting, so editing never fights background cleanup.
• Chase entities carry an enlarged culling radius so pursuits do not de-spawn at cinematic camera distances.

17. Troubleshooting#