Rendercore — Engine Documentation

Version 2.x  ·  C++17  ·  Windows 10 / 11  ·  Renderon Software 2025–2026

1. Overview

Rendercore is a proprietary C++ game engine built for open-world 3D games. It is designed around a GTA-style architecture: a large world with streaming, AI pedestrians, weapons, missions, cutscenes, interiors, vehicles, dynamic traffic, wanted levels, pickups, named zones with gang territories, a full day/night and weather cycle, a minimap system, a 3-slot save system — all in an integrated, editor-driven workflow.

The engine is built on top of EnTT (Entity Component System), OpenGL 4.x (rendering), Bullet3 (physics — rigid bodies, vehicles, character controllers, joints), OpenAL Soft (3D audio), Assimp (3D model importing), GLFW (windowing), GLM (math), nlohmann/json (serialization), and Dear ImGui (editor UI).

Language	C++17
ECS	EnTT
Renderer	OpenGL 4.x (forward renderer)
Audio	OpenAL Soft + libsndfile (WAV / OGG)
3D Import	Assimp (FBX, OBJ, GLTF, DAE…)
Physics	Bullet3 — rigid bodies, KCC, vehicle (btRaycastVehicle), joints, ghost triggers
Serialization	nlohmann/json (scenes, interiors, save files)
Scripting	Native C++ scripts + Lua Pipeline (in-engine, no recompile)
Platforms	Windows 10, Windows 11

2. Architecture — Entity Component System (ECS)

Rendercore uses an Entity Component System architecture via the EnTT library. Every object in the world — characters, vehicles, lights, triggers, roads, pickups, zones — is an entity: a plain integer handle. All data is stored in components attached to entities. All logic runs inside stateless systems that iterate over entities with specific component sets.

Entity     =  Integer ID  (e.g. 42)
Component  =  Pure data struct  (e.g. TransformComponent, VehicleComponent)
System     =  Logic that processes entities  (e.g. PhysicsSystem::Update, NPCSystem::Update)

The main entt::registry holds all entities and components for the current scene. Interior scenes have their own isolated registries. The engine runs systems in a defined order each frame:

ScriptSystem → LuaPipelineSystem → GtaCharacterControllerSystem::PreStep
→ BulletPhysicsWorld::Update (stepSimulation) → GtaCharacterControllerSystem::PostStep
→ JointSystem → VehicleSystem → VehicleEnterExitSystem
→ NPCSystem → ThirdPersonControllerSystem → WeaponSystem
→ TrafficSystem → WantedSystem → PickupSystem
→ WeatherSystem → ZoneSystem → MinimapSystem
→ AudioSourceSystem → StepSoundSystem → StreamingSystem
→ MissionSystem → CutsceneSystem → Renderer

3. Components

3.1 TransformComponent

Every entity that exists in 3D space requires a TransformComponent.

Field	Type	Description
Position	glm::vec3	World position (X, Y, Z)
Rotation	glm::vec3	Euler angles in degrees (Pitch, Yaw, Roll)
Scale	glm::vec3	Scale multiplier per axis (default 1,1,1)

The method GetTransform() returns the combined model matrix (TRS order).

3.2 MeshComponent

Attaches a 3D mesh and its animation state to an entity.

Field	Type	Description
FilePath	string	Path to the mesh file (FBX, OBJ, etc.)
AnimationList	vector<string>	Animation names embedded in the file
CreatedClips	vector<AnimationClip>	Editor-defined clips with custom frame ranges
CurrentAnimationIndex	int	Active animation track index
IsPlaying	bool	Whether the animation is currently playing
Loop	bool	Whether the animation loops
AnimationSpeed	float	Playback speed multiplier (default 1.0)
StartFrame / EndFrame	float	Frame range for the current clip
FreezeLastFrame	bool	When true, holds the final pose after animation ends (used by DeathAnim)
BoneWorldTransforms	map<string, mat4>	World transforms of all bones, populated each frame by the renderer

3.3 CameraComponent

Marks an entity as a renderable camera viewpoint.

Field	Type	Description
Primary	bool	If true, this camera is used for rendering
FOV	float	Field of view in degrees (default 60°)
NearClip / FarClip	float	Frustum near/far planes

3.4 RigidBodyComponent

Gives an entity Bullet3 physics simulation (gravity, velocity, collision response). A BulletRuntimeComponent is auto-created internally to store the btRigidBody pointer.

Field	Type	Description
Velocity	glm::vec3	Current linear velocity
Mass	float	Mass in kg (0 = static body)
UseGravity	bool	Whether gravity applies (default true)
IsKinematic	bool	If true, not affected by physics forces (moved manually)
IsGrounded	bool	Runtime — true when standing on a surface
MaxStepHeight	float	Max height of ledge the entity can step up automatically
FreezePosition X/Y/Z	bool	Lock movement per axis
FreezeRotation X/Y/Z	bool	Lock rotation per axis
Restitution	float	Bounciness (0 = no bounce, 1 = fully elastic)
LinearDamping / AngularDamping	float	Drag coefficients for linear and angular velocity

3.5 Collider Components

Rendercore supports four collision shapes, all backed by Bullet3 collision objects.

BoxColliderComponent — axis-aligned bounding box:

Field	Type	Description
Size	glm::vec3	Half-extents of the box
Offset	glm::vec3	Local offset from entity origin
IsTrigger	bool	If true, detects overlap but does not block movement

SphereColliderComponent — spherical collision shape:

Field	Type	Description
Radius	float	Sphere radius in meters
Offset	glm::vec3	Local offset
IsTrigger	bool	Trigger-only overlap

CapsuleColliderComponent — preferred shape for characters:

Field	Type	Description
Radius	float	Capsule radius
Height	float	Cylinder height (excluding hemispheres)
Offset	glm::vec3	Local offset

MeshColliderComponent — exact triangle mesh collision. Best for static geometry (terrain, buildings). Uses btBvhTriangleMeshShape for static or btConvexHullShape for dynamic bodies.

3.6 AudioSourceComponent

Attaches a sound source to an entity. Supports 3D positional audio via OpenAL.

Field	Type	Description
AudioFile	string	Path to .wav or .ogg file
Volume	float	0.0 to 1.0
Loop	bool	Whether the sound loops
Is3D	bool	If true, sound attenuates with distance from listener
MinDistance / MaxDistance	float	Attenuation range for 3D sound
PlayOnStart	bool	Automatically plays when game mode starts

3.7 ThirdPersonControllerComponent

The main player controller for non-vehicle gameplay. Provides third-person character movement, camera follow, weapon holding, aiming, and shooting.

Field	Type	Description
WalkSpeed / RunSpeed	float	Movement speeds in m/s
JumpForce	float	Vertical impulse applied on jump
CameraDistance / CameraHeight	float	Third-person camera offset
CameraSensitivity	float	Mouse look sensitivity
IdleAnim / WalkAnim / RunAnim / JumpAnim	string	Animation clip names
WeaponModelPath	string	Mesh file for the held weapon
IsHolding	bool	Whether the player is holding the weapon
WeaponDamage	float	Damage per shot
ShootRange	float	Maximum raycast range in meters
ShootCooldown	float	Seconds between shots
ScareRange	float	Radius in which NPCs react with fear when shooting
AttachBoneName	string	Name of the bone the weapon is attached to
WeaponAnimOffsets	map	Per-animation position/rotation/scale offsets for the weapon

3.8 GtaCharacterComponent NEW

A high-fidelity character controller that replaces Bullet's buggy btKinematicCharacterController. Uses a btRigidBody capsule with manually managed gravity, velocity, and ground detection via contactTest after each physics step. Rotation is fully locked on the angular axis so the capsule never tips over.

Field	Type	Description
Radius / Height	float	Capsule dimensions in meters
WalkSpeed / RunSpeed / SprintSpeed	float	Ground movement speeds
JumpImpulse	float	Upward velocity applied on jump
Gravity	float	Per-character gravity override (default –9.81)
SlopeLimit	float	Max walkable slope in degrees (default 45°)
AirControl	float	Directional influence while airborne (0–1)
IsGrounded	bool (runtime)	True when ground contact is detected after each step
IsRunning / IsSprinting	bool (runtime)	Current locomotion state

3.9 VehicleComponent NEW

Wraps a btRaycastVehicle. Add this alongside a RigidBodyComponent and BoxColliderComponent on the chassis entity. Define wheels via the WheelInfo list; front wheels with IsFrontWheel = true receive the steering angle.

Field	Type	Description
MaxEngineForce	float	Peak engine thrust in Newtons
MaxBrakeForce	float	Peak braking force in Newtons
MaxSteering	float	Max steering angle in radians
EngineForce / BrakeForce / SteeringAngle	float (runtime)	Current driving inputs
Wheels	vector<WheelInfo>	Wheel positions, radii, suspension parameters
UseKeyboardInput	bool	If true, WASD/arrow keys drive the vehicle directly
SpeedKmh	float (runtime)	Current speed exported by VehicleSystem each frame

API shortcuts available on VehicleSystem: SetThrottle(e, throttle01), SetBrake(e, brake01), SetSteering(e, angle).

3.10 NPCComponent

Controls all AI behaviour for a non-player character. See Section 7 — NPC & AI System for full details.

Field	Type	Description
State	NPCState	Current AI state (IDLE, WANDER, WALK_TO, RUN_TO, INVESTIGATE, CHASE, FLEE, TALK, HURT, DEAD)
Health / MaxHealth	float	Current and maximum health points (default 100)
IsDead	bool	Set to true when health reaches 0
WalkSpeed / RunSpeed	float	Movement speeds
SightRange / SightAngle	float	Vision cone parameters
HearRange	float	Sound detection radius
CanChase / CanFlee / CanWander	bool	AI behaviour flags
IsAggressive	bool	If true, NPC will chase and attack the player
IdleAnim / WalkAnim / RunAnim / HurtAnim / DeathAnim	string	Animation clip names per state
Waypoints	vector<NPCWaypoint>	Patrol path with optional wait times at each point
ScreamSound	string	.wav file played when the NPC is scared

3.11 StreamingComponent (LOD)

Enables Level-of-Detail and open-world streaming for an entity.

Field	Type	Description
MeshHigh / MeshLow	string	Mesh paths for high and low quality LODs
StreamNearDist	float	Distance below which HIGH mesh is used
StreamFarDist	float	Distance above which entity is culled entirely
DisablePhysicsWhenCulled	bool	Disables RigidBody when entity is culled (performance)

3.12 MissionComponent (Marker/Trigger)

Defines a zone trigger that can start missions, cutscenes, or scripts when a player enters or interacts.

Field	Type	Description
DisplayName	string	Name shown in the editor
TriggerType	enum	TOUCH, APPROACH, or INTERACT
TriggerAction	enum	START_MISSION, TRIGGER_CUTSCENE, RUN_SCRIPT, SHOW_MESSAGE
CutsceneName	string	Name of the cutscene to launch
ScriptName	string	Name of the script to execute
ShowBlip	bool	Show a minimap blip indicator
ApproachRadius	float	Detection radius for APPROACH type triggers

3.13 ScriptComponent

Attaches a named script to an entity. The script is looked up in the ScriptSystem's registry and called each frame.

Field	Type	Description
ScriptName	string	Name of the registered script function

3.14 Joint Components NEW

Physics constraints linking two Bullet3 rigid bodies. All joints share a NeedsRebuild flag that triggers reconstruction by JointSystem on the next frame. See Section 23 — Joint System.

• HingeJointComponent — single-axis hinge (doors, wheels). Supports motor control via SetHingeMotor().
• BallJointComponent — point-to-point ball-socket (ragdoll, chains).
• SliderJointComponent — linear prismatic constraint (elevator, piston). Supports motor via SetSliderMotor().
• SpringJointComponent — 6-DOF spring (suspension, soft constraints).
• FixedJointComponent — fully rigid weld between two bodies.

3.15 Force Field Components NEW

Volume-based forces applied each physics step to all overlapping rigid bodies.

Component	Description
WindZoneComponent	Applies a directional wind force (Direction × Strength) to bodies inside the volume
ExplosionForceComponent	Applies a radial outward impulse at detonation time — configurable radius, force, and upward modifier
BuoyancyVolumeComponent	Simulates water buoyancy for bodies whose center of mass is below the water surface plane

4. Physics System — Bullet3

Rendercore uses Bullet3 as its physics backend, managed by the BulletPhysicsWorld singleton. It replaces the earlier custom AABB solver and provides production-grade rigid bodies, kinematic character controllers, raycast vehicles, joints, and ghost-object triggers.

BulletPhysicsWorld Configuration

Parameter	Default	Description
GravityY	–9.81 m/s²	World gravity — set before Init()
FixedTimeStep	1/60 s	Physics sub-step size (60 Hz)
MaxSubSteps	10	Maximum sub-steps per frame (handles drops to ~10 FPS without losing steps)

Collision Shapes

Box → btBoxShape · Sphere → btSphereShape · Capsule → btCapsuleShape · Static Mesh → btBvhTriangleMeshShape · Dynamic Mesh → btConvexHullShape

Trigger Volumes

Ghost objects (btGhostObject) back all IsTrigger = true colliders. The world registers a btGhostPairCallback at init so overlaps are tracked per-frame. OnTriggerEnter and OnTriggerExit callbacks are exposed on BulletPhysicsWorld.

Bi-directional ECS ↔ Bullet Sync

Each frame, BulletPhysicsWorld::Update() synchronises Bullet simulation results back to TransformComponent positions and rotations. Kinematic bodies go the other direction: changes to TransformComponent are pushed into their Bullet motion state before stepSimulation.

GTA Character Controller (btRigidBody)

GtaCharacterControllerSystem runs in two passes around stepSimulation: PreStep applies the desired walk velocity; PostStep runs a contactTest to determine ground contact and resets the vertical velocity on landing. This avoids the double-gravity and walk-direction bugs present in Bullet's own KCC.

5. Rendering

Rendercore uses an OpenGL 4.x forward renderer. All scene entities with a MeshComponent and TransformComponent are drawn each frame.

Lighting

• Directional light (sun/moon) with configurable direction, color, and intensity — driven at runtime by WeatherSystem and the day/night cycle
• Point lights via PointLightComponent with radius and intensity
• Ambient light contribution blended from SkyboxSettings

Skinned Mesh Rendering

Bone matrices are computed by the animation system and uploaded to the shader as u_FinalBonesMatrices (uniform array of mat4). Up to 100 bones are supported per mesh. The shader switches between animated and static paths automatically based on whether bone data is present.

Framebuffer

The scene renders to an off-screen Framebuffer that is then displayed in the editor viewport. In game mode the framebuffer is blit directly to the window.

Skybox

Each scene and interior has a SkyboxSettings struct controlling sky color, horizon color, sun direction, fog density, and sun intensity. The WeatherSystem smoothly blends SkyboxSettings between weather profiles across transitions. Skybox is rendered as a full-screen gradient pass before scene geometry.

6. Animation System

Animation is driven by Assimp's skeletal animation data. The Mesh class handles bone transforms via CalculateBoneTransform() walking the node tree recursively.

Animation Clips

By default, an animation is the raw track embedded in the model file. The editor allows creating custom clips (AnimationClip) that define a sub-range of frames (StartFrame → EndFrame), a loop flag, and a speed multiplier.

Field	Description
Name	Clip identifier used to reference it by name from NPC/TPC components
SourceAnimIndex	Index in the model's AnimationList
StartFrame / EndFrame	Frame range (0 = start of full animation)
Loop	Whether this clip loops
Speed	Playback speed multiplier

DeathAnim — Freeze on Last Frame

When an NPC dies, NPCSystem sets FreezeLastFrame = true on the MeshComponent and plays the DeathAnim with Loop = false. Once the animation finishes (IsPlaying = false), the renderer continues calling UpdateAnimation() without advancing time — holding the final bone pose permanently. This prevents the T-pose fallback.

7. NPC & AI System

NPCSystem provides a full GTA-style pedestrian AI with a state machine, perception, sidewalk navigation, and combat reactions.

State Machine

State	Behaviour
IDLE	Standing still, plays IdleAnim
WANDER	Walks randomly within WanderRadius, follows sidewalks if available
WALK_TO	Walks toward a specific TargetPoint
RUN_TO	Runs toward a specific TargetPoint
INVESTIGATE	Heard a sound, moves toward its origin
CHASE	Runs after the player (requires IsAggressive)
FLEE	Runs away from a threat
TALK	Plays TalkAnim, displays DialogueLine for DialogueTime seconds
HURT	Plays HurtAnim, then transitions to FLEE after HurtFleeDelay
DEAD	DeathAnim plays once and freezes. No further state changes.

Perception

• Sight — cone check using SightRange and SightAngle
• Hearing — radius check using HearRange
• Alert — large radius for gunshot reactions using AlertRange
• ScareRange — proximity to player with active weapon causes FLEE

Sidewalk Navigation

NPCs automatically detect nearby SidewalkComponent segments generated by the road system and navigate along them when wandering. They pass seamlessly between connected segments (proximity < 3 m).

Waypoints

Each NPC can have a list of NPCWaypoint entries defining a patrol path. Optional WaitTime per waypoint makes the NPC pause before moving to the next. LoopWaypoints controls whether the patrol repeats.

Combat & Health

When hit by a weapon raycast (WeaponSystem::ApplyHitToNPC), the NPC's health decreases. Below zero, IsDead = true, state → DEAD, RigidBody → kinematic. The DeathAnim plays once and the NPC stays on the ground permanently.

API

NPCSystem::WalkTo(npc, targetPosition);
NPCSystem::RunTo(npc, targetPosition);
NPCSystem::StartTalk(npc, "Hello there!", 3.0f);

8. Weapon System

The WeaponSystem manages weapon attachment, aiming, shooting, and hit detection for entities with a ThirdPersonControllerComponent.

Weapon Attachment

When IsHolding = true, a new entity is created at runtime holding the weapon mesh. It is parented to a specific bone (AttachBoneName) on the player's skeleton. Per-animation position/rotation/scale offsets (WeaponAnimOffsets) fine-tune the weapon's alignment for each animation clip.

Shooting

Shooting uses a raycast from the camera origin in the aim direction. The ray is tested against all NPC entities using a closest-hit algorithm. A perpendicular distance check of 0.5 m from the NPC center determines a hit. Each shot also increments the player's wanted infraction points in WantedSystem if a pedestrian is hit.

Scare Range

Each shot triggers ApplyScareRange() — all NPCs within ScareRange radius and not directly hit will react by switching to the FLEE state.

Fire Slot / Flash

A bone named by WeaponFireSlotName (e.g. "Fire") acts as the muzzle flash origin. A fire texture is swapped in for WeaponFireDuration seconds after each shot.

Weapon Anim Editor

The editor includes a dedicated Weapon Anim Editor panel allowing fine adjustment of the weapon's position, rotation, and scale for each individual animation — without changing the animation itself. Changes are stored per-animation in WeaponAnimOffsets.

9. Audio Engine

The AudioEngine wraps OpenAL Soft with convenience features for game audio. Sound files are decoded using libsndfile (WAV, OGG).

Volume Categories

Category	Description
SFX	Sound effects (footsteps, impacts, gunshots, pickups)
Music	Background music tracks
Voice	Dialogue and character voices
Ambiance	Environmental ambient sounds (weather, traffic)

3D Positional Audio

AudioSourceComponent with Is3D = true creates an OpenAL source at the entity's world position. The listener is updated each frame to match the player/camera position. Sound attenuates between MinDistance and MaxDistance.

Step Sound System

StepSoundSystem automatically fires footstep sounds at the correct interval based on whether the character is walking or running. Configurable parameters:

Field	Description
StepInterval	Seconds between footsteps while walking
RunStepInterval	Seconds between footsteps while running
Volume	Base step volume
VolumeVariance	Random variation added each step

10. Streaming System (LOD)

The StreamingSystem provides open-world entity streaming similar to GTA San Andreas. It runs on a configurable interval (default 0.1s) and adjusts each entity's mesh and physics based on its distance from the camera/player.

LOD Levels

Level	Condition	Behaviour
HIGH	Distance < StreamNearDist	Full quality mesh, physics active
MEDIUM	Between near and mid distance	Standard mesh
LOW	Between mid and StreamFarDist	Low quality mesh
CULLED	Distance > StreamFarDist	Entity hidden, physics optionally disabled

The system fires a MeshLoadRequestCallback when a LOD swap is needed, allowing the renderer to load the new mesh asynchronously.

11. Mission System

The MissionSystem provides GTA-style trigger zones that launch missions, cutscenes, scripts, or messages.

Trigger Types

Type	Description
TOUCH	Fires when the player physically overlaps the trigger volume
APPROACH	Fires when the player enters ApproachRadius
INTERACT	Fires when the player presses the interact key inside the zone

Actions

Action	Description
START_MISSION	Sets a mission as active in MissionState
TRIGGER_CUTSCENE	Starts a named cutscene from the scene registry
RUN_SCRIPT	Executes a named script on the trigger entity
SHOW_MESSAGE	Displays a HUD message for a configurable duration

Mission State

Global state is tracked in MissionState: active mission ID, list of completed missions, list of failed missions.

12. Cutscene System

The CutsceneSystem provides a timeline-based cinematic system. Cutscenes are stored per-scene in a SceneCutsceneRegistry entity.

Structure

• CutsceneData — one cutscene: name, duration, loop flag, list of tracks
• CutsceneTrackData — one track: target entity (by name tag), list of keyframes, track type (Position, Rotation, Animation, Camera, Audio…)
• CutsceneKeyframeData — one keyframe: time, value, easing

Playback

• Play, Pause, Resume, Seek, Stop
• Entities are resolved by TagComponent name at runtime
• An OnFinished callback fires with the cutscene name when playback ends
• Cutscene cameras override the main camera during playback and are restored after Stop

Serialization

Cutscenes are serialized to/from JSON by CutsceneSerializer as part of the scene file.

13. Interior System

Rendercore supports multiple isolated interior scenes inside a single project. Each interior has its own entt::registry, its own skybox settings, and its own audio space.

InteriorContext

Field	Description
ID	Auto-generated unique identifier
Name	Display name in the editor
Registry	Isolated ECS registry for all interior entities
Skybox	Indoor sky/ambient settings

The Interior Editor allows creating, naming, and populating interiors. Transitions between the exterior and an interior are triggered via MissionComponent zones.

14. Road System

The RoadGenerator procedurally creates road mesh geometry from RoadComponent data. Roads are fully editable in the editor and automatically generate sidewalk segments for NPC navigation and traffic waypoints for the TrafficSystem.

Road Types

Type	Description
STRAIGHT	A straight road segment
CORNER_90	A 90° turn
T_JUNCTION	A T-shaped intersection
CROSSROAD	A 4-way intersection

Sidewalks

Each road entity automatically generates a SidewalkComponent with two segments (left and right sidewalk). NPCSystem uses these segments for pedestrian routing. NPCs automatically switch between connected segments when within 3 m of a junction.

15. Vehicle System NEW

Rendercore provides a full GTA-style vehicle system built on Bullet3's btRaycastVehicle. Vehicles support physics-accurate suspension, engine force, braking, and steering — with optional keyboard input or full programmatic control via VehicleSystem API calls.

Setup

To create a driveable vehicle:

• Add RigidBodyComponent (non-zero mass) + BoxColliderComponent on the chassis entity.
• Add VehicleComponent and populate the Wheels list with at least 4 WheelInfo entries.
• Front wheels should have IsFrontWheel = true to receive steering.
• Optionally set UseKeyboardInput = true to wire WASD/arrows directly.

WheelInfo Parameters

Field	Description
ConnectionPoint	Wheel attachment point in chassis local space
WheelRadius	Wheel radius in meters
SuspensionRestLength	Rest length of suspension spring
SuspensionStiffness	Spring stiffness coefficient
WheelsDampingRelaxation / Compression	Damping rates
FrictionSlip	Grip coefficient (higher = more traction)
IsFrontWheel	Receives steering angle if true

Enter / Exit System

The VehicleEnterExitSystem handles GTA-style vehicle boarding. The player presses F when within SearchRadius (default 8 m) of a vehicle with a VehicleInteractionComponent. While seated, the player entity is hidden and anchored to the vehicle; the camera switches to a third-person vehicle follow mode. Pressing F again or Escape exits.

Multi-seat support: seat index 0 = driver, index 1..N = passengers. If the driver seat is occupied, a nearby entity will board as a passenger.

16. Traffic System NEW

The TrafficSystem provides dynamic open-world vehicle and pedestrian traffic with GTA-style pool recycling. Vehicles and pedestrians spawn in a configurable radius around the player, follow road waypoints, obey traffic lights, and despawn when too far away.

Traffic Waypoints

Place TrafficWaypointComponent entities at road nodes to define the traffic network. Each waypoint has a list of NextWaypoints (outgoing connections), a speed limit, and optional traffic light parameters.

Field	Description
NextWaypoints	Outgoing connections in the road graph
SpeedLimit	Target speed on this segment (m/s, default 15 m/s ≈ 54 km/h)
IsIntersection	Priority node — vehicles yield at intersections
HasTrafficLight	Enable traffic light state machine at this node
LightCycleTime	Duration of one green/red cycle in seconds (default 8 s)

Vehicle AI

Traffic vehicles follow the waypoint graph using VehicleSystem::SetThrottle / SetSteering. They slow for red lights and yield at intersections. On collision they honk and attempt evasion. Density is configurable per NamedZone (see Section 19 — Zone System).

Pedestrian Traffic

Pedestrians spawn on sidewalks and walk between waypoints using NPCSystem locomotion. They are pooled and recycled along with vehicles when the player moves through the world.

17. Wanted System NEW

The WantedSystem implements a 6-star police pursuit model matching GTA San Andreas mechanics. Infractions accumulate points; crossing a star threshold spawns the appropriate law enforcement tier and activates a BOLO search circle.

Wanted Levels

Stars	Response
★☆☆☆☆☆ (1)	2 police officers on foot
★★☆☆☆☆ (2)	4 officers + 1 patrol car
★★★☆☆☆ (3)	+ Police helicopter
★★★★☆☆ (4)	+ FBI vehicles + roadblocks
★★★★★☆ (5)	+ FBI agents on foot + tanks
★★★★★★ (6)	Army (Hydra jets, Rhino tanks)

Star Thresholds (default)

Stars are awarded at infraction point totals: 10 · 25 · 60 · 120 · 250 · 500. Each threshold is configurable via WantedSettings.StarThresholds[6].

Decay & Evasion

When the player escapes the BOLO circle and stays out of sight, the infraction score decays over time and the wanted level drops. Remaining inside the circle resets the decay timer.

Reduction Methods

Method	Effect
Evasion (out of sight + BOLO exit)	Gradual score decay → level drops
Pay-n-Spray	Instant full clear (trigger via WantedSystem::PayNSpray())
Bribe pickup	–1 star (via PickupType::WANTED_DEC)
Player death / arrest	Resets to 0

HUD Integration

The current wanted level (0–6 stars) is exposed to UIRenderer for HUD rendering.

18. Pickup System NEW

The PickupSystem manages GTA-style collectibles with spin + bob animations, a glow point light, optional respawning, a collection sound, and callbacks to player stats or inventory systems.

Pickup Types

Type	Value / Effect
HEALTH	+25 HP (configurable via Value)
HEALTH_FULL	Full HP restore
ARMOR	+25 armor
BODY_ARMOR	Full armor restore
WEAPON	Grants weapon + ammo (set WeaponName)
AMMO	Ammo only for existing weapon
MONEY	+$250 (configurable via Value)
WANTED_DEC	–1 wanted star (GTA-style bribe)
NITRO	Vehicle boost charge
PARACHUTE	Grants parachute item
ADRENALINE	Slow-motion effect (GTA III legacy)
MISSION	Custom mission pickup (set MissionID)

PickupComponent Fields

Field	Description
Type	Pickup category (enum above)
Value	Numeric amount applied (HP, $, ammo, etc.)
WeaponName / MissionID	Contextual payload for WEAPON / MISSION types
CollectRadius	Trigger radius in meters
RespawnTime	Seconds until the pickup reappears (0 = one-shot)
RotateSpeed / BobAmplitude / BobSpeed	Animation parameters
GlowColor	Point light color of the halo
CollectSound	WAV path played on collection

19. Zone System NEW

The ZoneSystem manages named geographic regions (city districts, deserts, airports) and reports the player's current zone to the HUD. The GangTerritorySystem extends this with hex-tile gang territories, capture mechanics, and minimap overlays.

NamedZone

Field	Description
Name / ShortName	Display name and abbreviation (e.g. "Los Santos" / "LS")
Type	CITY, SUBURB, RURAL, DESERT, MOUNTAIN, WATER, AIRPORT, INTERIOR
MinXZ / MaxXZ	2D AABB in world X/Z (Y is ignored — 2D zone lookup)
MinimapColor	Zone overlay color on the minimap
TrafficDensityOverride	Multiplier applied to global traffic density in this zone
WeatherOverride	Optional forced weather state inside this zone

Gang Territory System

Territories are hex-tile grids; each tile belongs to a gang faction. The player can trigger gang wars by entering enemy territory with sufficient wanted rep. Tiles flip faction when a war is won. Controlled tiles spawn friendly NPC reinforcements; enemy tiles spawn hostile gang members. Territory state is saved and loaded by the SaveSystem.

20. Weather & Day/Night System NEW

The WeatherSystem manages a continuous 24-hour day/night cycle and 8 distinct weather states with smooth cross-fading between profiles. All visual changes are applied directly to SkyboxSettings and the renderer's directional light each frame.

Weather States

State	Description
SUNNY	Bright clear sky, strong directional light
CLEAR	Clear sky with softer light
CLOUDY	Overcast with diffuse ambient
OVERCAST	Heavy cloud cover, dim light
RAIN	Light rain — activates rain particle system, reduces player speed
STORM	Violent rain + lightning flashes, heavy fog
FOG	Dense ground fog, near-zero visibility at distance
SMOG	Urban smog layer (Los Santos style)

Day/Night Cycle

The simulated clock runs at a configurable speed multiplier (e.g. ×30 = one real minute equals 30 in-game minutes). Sun and moon positions are computed physically from the current in-game hour. Ambient and directional light colors shift through sunrise, noon, sunset, and night palettes automatically.

Gameplay Effects

• Rain reduces player walk/run speed by a configurable factor
• Storm and rain increase vehicle tyre slip (reduces FrictionSlip)
• Zone weather overrides take priority over the global weather state

21. Minimap System NEW

The MinimapSystem renders a circular radar HUD in the corner of the screen using a dedicated OpenGL 2D orthographic pass. It matches the GTA San Andreas minimap in feature set.

Features

• Circular mask with configurable radius and scale (zoom in/out)
• Optional north-fixed or player-rotated orientation
• Player arrow at the center of the disc
• Gang territory zone color overlays
• Configurable blip system — see table below

Blip Types

BlipType	Description
PLAYER	White arrow — always at center
ENEMY	Red dot — hostile NPCs in range
FRIENDLY	Green dot — allied NPCs
MISSION	Yellow star — active mission marker
VEHICLE	Cyan dot — nearby driveable vehicles
PICKUP	Green cross — health/item pickups
SHOP	Dollar sign — Pay-n-Spray, Ammu-Nation, etc.
SAVE_POINT	Floppy disk icon — save point locations
WAYPOINT	Pulsing marker — player-placed or mission waypoint

22. Save System NEW

The SaveSystem provides 3-slot JSON save files matching the GTA San Andreas save model. It serializes all persistent game state and validates integrity via a simple checksum.

Saved State

• Player position, health, armor, and money
• Active and completed mission IDs
• Weapon inventory and ammo counts
• Gang territory ownership
• Current in-game time and weather state
• Custom flags (set via SaveSystem::SetFlag(key, value))

SavePointComponent

Add SavePointComponent to any entity (house, checkpoint) to make it a save trigger. When the player interacts, the SaveSystem opens the slot selection UI and writes the chosen slot to saves/slot_N.json.

Auto-Save

Auto-save interval is configurable (default disabled). When enabled, the last used slot is overwritten silently.

Integrity

Each save file stores a CRC checksum in its header. A mismatch on load triggers a corruption warning and prevents loading.

API

SaveSystem::Save(slotIndex, registry);     // write slot
SaveSystem::Load(slotIndex, registry);     // restore state
SaveSystem::SetFlag("door_open", true);    // custom persistent flag
bool v = SaveSystem::GetFlag("door_open"); // read flag

23. Joint System NEW

The JointSystem manages Bullet3 constraints between pairs of rigid bodies. Joints are defined via components on either of the two connected entities; set NeedsRebuild = true to trigger reconstruction on the next frame. JointSystem::Update(registry) is called once per frame after BulletPhysicsWorld::Update().

Joint Types

Component	Bullet Constraint	Typical Use
HingeJointComponent	btHingeConstraint	Doors, gates, rotating platforms. Motor: JointSystem::SetHingeMotor(e, velocity, impulse)
BallJointComponent	btPoint2PointConstraint	Ragdoll joints, rope links, swinging objects
SliderJointComponent	btSliderConstraint	Elevators, pistons, drawers. Motor: JointSystem::SetSliderMotor(e, velocity, force)
SpringJointComponent	btGeneric6DofSpring2Constraint	Soft-body suspension, elastic constraints
FixedJointComponent	btFixedConstraint	Welding two dynamic bodies together rigidly

Breaking Joints

Call JointSystem::BreakJoint(entity, registry) to destroy a constraint and remove the joint component at runtime (e.g. destructible environment).

24. Scripting (C++)

Scripts are native C++ functions registered in the ScriptSystem under a string name. Any entity with a ScriptComponent calls its registered function each frame. For a no-recompile, in-engine alternative, see Section 25 — Lua Pipeline.

Script Signature

void MyScript(entt::registry& registry, entt::entity entity, float dt, GLFWwindow* window) {
    // Access any component:
    auto& transform = registry.get<TransformComponent>(entity);
    transform.Position.y += 1.0f * dt;
}

Registering a Script

ScriptSystem scripts;
scripts.Register("MyScript", MyScript);

Then assign "MyScript" to the entity's ScriptComponent.ScriptName in the editor.

25. Lua Pipeline

25.1 Lua Components

A Lua Component is a named data container that can be attached to any entity in the scene. It is defined in the Lua Pipeline Editor (Toolbar → "Lua Pipeline") and persisted to assets/lua_pipeline/components/<Name>.lua.

Lua Component definition

RegisterComponent({
    name        = "HealthBar",
    displayName = "Health Bar",
    category    = "Gameplay",
    description = "Tracks entity health with optional passive regeneration.",
    fields = {
        { name = "MaxHealth",     type = "float",  default = 100.0 },
        { name = "CurrentHealth", type = "float",  default = 100.0 },
        {
            name    = "Regeneration",
            type    = "range",
            default = 0.0,
            min     = 0.0,
            max     = 10.0,
            tooltip = "HP per second recovered passively",
        },
        {
            name   = "DamageType",
            type   = "enum",
            values = { "Physical", "Fire", "Poison" },
            default = 0,
        },
    },

    onAdd    = "OnHealthBarAdd",
    onUpdate = "OnHealthBarUpdate",
    onRemove = "OnHealthBarRemove",
})

function OnHealthBarAdd(entity)
    Debug.Log("HealthBar added to " .. Entity.GetTag(entity))
end

function OnHealthBarUpdate(entity, dt)
    local comp = Entity.GetLuaComponent(entity, "HealthBar")
    if comp.Regeneration > 0 then
        Entity.SetLuaField(entity, "HealthBar", "CurrentHealth",
            Math.Clamp(comp.CurrentHealth + comp.Regeneration * dt, 0, comp.MaxHealth))
    end
end

function OnHealthBarRemove(entity)
    Debug.Log("HealthBar removed")
end

25.2 Field Types

The following field types are available in Lua Component definitions:

Type	Inspector Widget	Extra Options
float	Drag float	min, max, step
int	Drag int	min, max
bool	Checkbox	—
string	Text input	—
vec2	2-component drag	—
vec3	3-component drag	—
color	Color picker (RGBA)	—
range	Slider	min, max (required)
enum	Dropdown	values = { … } (required)

25.3 Lua Systems

A Lua System runs every frame and can query entities, read/write components, and emit events.

Lua System example

-- System: ProximityAlert
-- Checks all "Enemy" entities against the player each frame

RegisterSystem({
    name         = "ProximityAlert",
    displayName  = "Proximity Alert",
    priority     = 50,
    runInRuntime = true,
    runInEditor  = false,
    onUpdate     = "ProximityAlert_Update",
})

function ProximityAlert_Update(dt)
    local player = Entity.FindByTag("Player")
    if not Entity.IsValid(player) then return end

    local px, py, pz = Entity.GetPosition(player)
    local enemies = Entity.FindAllByTag("Enemy")

    for _, e in ipairs(enemies) do
        local ex, ey, ez = Entity.GetPosition(e)
        local dist = Math.Distance(Math.Vec3(px,py,pz), Math.Vec3(ex,ey,ez))
        if dist < 5.0 then
            Events.Emit("EnemyNear", { entity = e, distance = dist })
            Debug.Warn("Enemy nearby: " .. dist .. "m")
        end
    end
end

25.4 Pipeline API Reference

Function	Description
Entity.FindByTag(tag)	Returns the first entity with the given tag, or nil
Entity.FindAllByTag(tag)	Returns a table of all entities with the given tag
Entity.IsValid(entity)	Returns true if the entity handle is valid
Entity.GetTag(entity)	Returns the entity's tag string
Entity.GetPosition(entity)	Returns x, y, z world position
Entity.SetPosition(entity, x, y, z)	Teleports entity to position
Entity.GetLuaComponent(entity, name)	Returns the Lua component table by name
Entity.SetLuaField(entity, comp, field, value)	Sets a single field on a Lua component
Math.Distance(a, b)	Returns distance between two vec3 values
Math.Clamp(v, min, max)	Clamps a number between min and max
Math.Vec3(x, y, z)	Constructs a vec3 table
Events.Emit(name, data)	Broadcasts a named event with a payload table
Events.On(name, callback)	Registers a listener for a named event
Debug.Log(msg)	Prints an info message to the console
Debug.Warn(msg)	Prints a warning message to the console
Debug.Error(msg)	Prints an error message to the console

25.5 Generated Code / Boilerplate

When you create a new Component or System in the Pipeline Editor, Rendercore generates a boilerplate stub automatically. For a component, the stub includes all lifecycle callbacks; for a system, it includes the update function and a commented-out example query.

25.6 Inspector Integration

Lua Components added to an entity appear directly in the entity Inspector alongside native C++ components, in a dedicated section labeled "Lua Components".

• Each component has a collapsible header with an Enabled checkbox and an ✕ remove button.
• All fields are rendered as editable widgets matching their type (slider, checkbox, color picker, dropdown, etc.).
• The description is shown as inline text below the header. Tooltips appear on hover over each field.
• An "Edit in Pipeline" button opens the Lua Pipeline Editor focused on that component's definition.

To add a Lua Component to an entity, click Add Component in the Inspector. Lua components appear grouped by category at the bottom of the menu. Components already attached to the selected entity are shown as disabled (✓).

25.7 Persistence & Hot-Reload

All definitions are automatically saved to disk:

assets/
└── lua_pipeline/
    ├── components/
    │   ├── HealthBar.lua
    │   └── DialogueTrigger.lua
    └── systems/
        ├── ProximityAlert.lua
        └── DayNightCycle.lua

Each file embeds its metadata (name, display name, fields, priority, etc.) in a --[[PIPELINE ... PIPELINE_END]] header block comment, followed by the Lua code body. The engine reads all files in these directories on startup via LuaPipelineEditor::LoadAllFromDisk().

26. Serialization

Scenes are saved and loaded as JSON files by SceneSerializer. Every supported component is serialized when present on an entity.

Supported Components (Serialized)

TagComponent, TransformComponent, MeshComponent (including AnimationClips, materials, textures), CameraComponent, PointLightComponent, RigidBodyComponent, BoxColliderComponent, SphereColliderComponent, CapsuleColliderComponent, MeshColliderComponent, AudioSourceComponent, StepSoundComponent, ThirdPersonControllerComponent (including WeaponAnimOffsets), GtaCharacterComponent, VehicleComponent (including WheelInfo list), VehicleInteractionComponent, NPCComponent (including Waypoints), MissionComponent, StreamingComponent, ScriptComponent, HingeJointComponent, BallJointComponent, SliderJointComponent, SpringJointComponent, FixedJointComponent, WindZoneComponent, ExplosionForceComponent, BuoyancyVolumeComponent, PickupComponent, TrafficWaypointComponent, SavePointComponent, SkyboxSettings, CutsceneRegistry, LuaComponentInstances.

Interior Serialization

Interiors are serialized separately by InteriorSerializer — each interior is saved as an independent JSON object embedded in or alongside the main scene file.

Save Files

Game save data (player stats, missions, territory, time/weather) is written by SaveSystem to saves/slot_N.json, separate from scene files. Scene files are editor assets; save files are runtime player data.

Scene File Structure (summary)

{
  "entities": [
    {
      "tag": "Player",
      "Transform": { "Position": [0,1,0], "Rotation": [0,0,0], "Scale": [1,1,1] },
      "Mesh": { "FilePath": "assets/player.fbx", ... },
      "GtaCharacter": { "WalkSpeed": 3.5, "JumpImpulse": 6.0, ... }
    },
    {
      "tag": "Taxi",
      "Transform": { ... },
      "RigidBody": { "Mass": 1200.0, ... },
      "Vehicle": { "MaxEngineForce": 1500.0, "Wheels": [...] }
    },
    ...
  ],
  "skybox": { ... },
  "cutscenes": [ ... ],
  "interiors": [ ... ]
}

27. Editors

Rendercore ships with a fully integrated suite of editors accessible from the main editor window.

Scene Editor (EditorGui)

• Entity hierarchy panel — create, select, duplicate, delete entities
• Inspector panel — view and edit all components on the selected entity (including new Vehicle, GtaCharacter, Joint, and Pickup components)
• Transform gizmos (Translate / Rotate / Scale) in the 3D viewport
• Drag-and-drop asset assignment for meshes, textures, audio files
• Play / Stop game mode toggle
• Engine Stats window (FPS, frame time, entity count, streaming stats, mission state, wanted level, active traffic count)
• Hitbox and joint debug overlay

Mission Editor

Visual editor for placing and configuring MissionComponent trigger zones. Supports box and sphere trigger shapes, trigger type selection, and action wiring.

Lua Pipeline Editor

The primary interface for defining custom Lua Components and Systems. Accessible via Toolbar → "Lua Pipeline". Three-column layout: sidebar (component/system list with dirty indicators ●), center panel (Fields, Code, and Settings tabs), and an optional live API Reference panel (Help → "Show API Reference"). Supports Ctrl+S hot-reload, duplicate/delete via right-click context menu, and a built-in Lua code editor with syntax highlighting and Pipeline API keyword coloring.

Cutscene Editor

Timeline-based editor with track lanes per entity. Supports adding position, rotation, animation, camera, and audio keyframes. Real-time preview with play/pause/seek controls.

Interior Editor

Create and manage interior scenes. Each interior opens as a separate tab in the 3D viewport with its own entity list and skybox settings.

Script Editor

Basic in-editor code viewer and selector for C++ scripts attached to entities. For Lua scripting, use the dedicated Lua Pipeline Editor instead.

Weapon Anim Editor

Per-animation position/rotation/scale offset editor for the weapon mesh attachment. Preview the weapon pose live while scrubbing the animation in the viewport.

Road Editor

Place road segments by type (Straight, Corner, T-Junction, Crossroad), adjust width, material textures, and sidewalk parameters. Roads update their mesh geometry in real time. Road placement also auto-generates TrafficWaypointComponent nodes for the Traffic System.

Traffic Editor NEW

Visual editor for the traffic waypoint network. Displays nodes and connections as an overlay in the 3D viewport. Allows adding, connecting, and configuring waypoints including traffic light parameters. Simulates vehicle pathing from selected nodes for preview.

UI Editor

Editor for in-game UI elements (HUD, menus). Uses the UISystem and UIComponents for building screen-space interfaces.

28. Licenses & Pricing

Rendercore is available under four license tiers designed to fit solo developers, indie studios, and commercial production teams. All licenses grant access to the full engine binary and editor, including all new systems (Bullet3 physics, Vehicle, Traffic, Wanted, Pickup, Zone, Weather, Minimap, Save, Joint systems). Source code access is available on Studio and Enterprise tiers.

License Comparison

Feature	Community	Indie	Studio	Enterprise
Full engine & editor	✓	✓	✓	✓
All gameplay systems (Vehicle, Wanted, Weather…)	✓	✓	✓	✓
Lua Pipeline	✓	✓	✓	✓
Commercial release	—	✓ (<$200K/yr)	✓ (unlimited)	✓ (custom terms)
C++ source code	—	—	✓	✓
Remove splash screen	—	—	✓	✓
Support SLA	Forum	72h	24h	Dedicated
Max seats	1	5	Unlimited	Unlimited
Price (per seat/mo)	Free	$39	$159	Contact us

Revenue Threshold & Royalties

Rendercore does not charge any royalties or revenue share on shipped titles. The only revenue restriction applies to the Indie tier: projects generating over $200,000 USD in gross revenue per calendar year must upgrade to a Studio or Enterprise license within 60 days of crossing the threshold. There are no back-payments owed on revenue earned below the cap.

Purchasing & Activation

Licenses are purchased and managed at renderon.net/rendercore/license. After purchase, a license key is emailed to your account address. Activate it from Editor → Help → Activate License. Each key is tied to one machine at a time; you may transfer to a new machine by deactivating the current one from your account dashboard.

Refund Policy

Monthly subscriptions may be cancelled at any time; access continues until the end of the billing period. Annual subscriptions are refundable within 14 days of purchase if the engine has not been used to ship a commercial product. To request a refund, contact billing@renderon.net.