diff --git a/.claude/index.md b/.claude/index.md index da205f8f6..b6157b9e8 100644 --- a/.claude/index.md +++ b/.claude/index.md @@ -24,7 +24,7 @@ _Read this at every session start (after git sync). Each row links to a detailed | Rendering pipeline (all 12 stubs now implemented) | [knowledge/rendering-pipeline-status.md](knowledge/rendering-pipeline-status.md) | Observation | **Resolved** | 2026-03-22 | | Engine systems (29+ working, all wired) | [knowledge/gameplay-systems-status.md](knowledge/gameplay-systems-status.md) | Observation | Active | 2026-03-22 | | SparkGame module (AI enemies now wired) | [knowledge/sparkgame-module-status.md](knowledge/sparkgame-module-status.md) | Observation | Active | 2026-03-22 | -| Documentation coverage (83 wiki pages, 99.6% Doxygen) | [knowledge/documentation-coverage-audit.md](knowledge/documentation-coverage-audit.md) | Observation | Active | 2026-04-02 | +| Documentation coverage (88 wiki pages, 99.6% Doxygen) | [knowledge/documentation-coverage-audit.md](knowledge/documentation-coverage-audit.md) | Observation | Active | 2026-04-03 | | ThirdParty dependencies | [knowledge/thirdparty-dependencies-audit.md](knowledge/thirdparty-dependencies-audit.md) | Observation | Active | 2026-03-17 | | Load test baseline (frame/CPU/memory benchmarks) | [knowledge/load-test-baseline.md](knowledge/load-test-baseline.md) | Observation | Active | 2026-03-26 | | Live editor testing (Xvfb + Mesa llvmpipe) | [knowledge/live-editor-testing.md](knowledge/live-editor-testing.md) | Pattern | Active | 2026-03-28 | diff --git a/.claude/knowledge/documentation-coverage-audit.md b/.claude/knowledge/documentation-coverage-audit.md index 8c0f7361c..09155e8ef 100644 --- a/.claude/knowledge/documentation-coverage-audit.md +++ b/.claude/knowledge/documentation-coverage-audit.md @@ -1,23 +1,34 @@ # Documentation Coverage Audit -**Last updated:** 2026-04-02 +**Last updated:** 2026-04-03 **Type:** Observation **Status:** Active **Severity:** Low ## Description -83 wiki pages (excluding _Sidebar.md), 245/246 headers with Doxygen comments, near-complete API coverage. Added 13 new wiki pages covering advanced graphics subsystems, tween system, error handling patterns, and hot-reload overview. +88 wiki pages (excluding _Sidebar.md), 245/246 headers with Doxygen comments, near-complete API coverage. Added 5 new user-facing wiki pages: FAQ, Quick-Start Tutorial, Editor Walkthrough, Configuration Reference, Performance Tips. Updated Home.md with role-based reading paths. --- ## Wiki Coverage (83 pages) ### Statistics -- **Total pages**: 83 (excluding _Sidebar.md) +- **Total pages**: 88 (excluding _Sidebar.md) - All engine subsystems have wiki pages (including Tween System, previously missing) - All major graphics subsystems documented (Render Graph, GPU Particles, GPU-Driven Rendering, Volumetric Fog, Global Illumination, Virtual Texturing, Water Rendering, Clustered Lighting, Mesh Shaders, Shader Graph) - Broad topic pages added: Error Handling Patterns, Hot Reload Overview +- User-facing docs added: FAQ, Quick-Start Tutorial, Editor Walkthrough, Configuration Reference, Performance Tips + +### New Pages Added (2026-04-03) + +| Page | Category | Coverage | +|------|----------|----------| +| `FAQ.md` | Getting Started | Common questions: general, building, editor, gameplay, graphics, physics, audio, modding | +| `Quick-Start-Tutorial.md` | Getting Started | First 10 minutes: launch, console, editor, spawn objects, adjust world, graphics | +| `Editor-Walkthrough.md` | Getting Started | Practical hands-on editor guide: navigation, panels, workflows, play mode, shortcuts | +| `Configuration-Reference.md` | Advanced | Complete settings.ini reference, 150+ console commands, CVar system | +| `Performance-Tips.md` | Advanced | Optimization for rendering, physics, audio, networking, scripting, animation | ### New Pages Added (2026-04-02) diff --git a/wiki/Configuration-Reference.md b/wiki/Configuration-Reference.md new file mode 100644 index 000000000..08cb9d12e --- /dev/null +++ b/wiki/Configuration-Reference.md @@ -0,0 +1,561 @@ +# Configuration Reference + +Complete reference for SparkEngine settings, console commands, and console variables. This page covers everything you can configure without recompiling the engine. + +--- + +## Settings File + +SparkEngine loads settings from an INI file at startup. + +**Location** (searched in order): +1. `Resources/Config/settings.ini` (relative to executable) +2. `../Resources/Config/settings.ini` (one level up, common in dev builds) +3. Falls back to defaults if not found + +**Format:** + +```ini +# Comments start with # or ; +[SectionName] +Key = Value +``` + +Boolean values accept: `true`/`false`, `1`/`0`, `yes`/`no`, `on`/`off`. + +### Managing Settings at Runtime + +Use the console to read and modify settings without editing the file: + +``` +settings_list # List all settings +settings_sections # List all sections +settings_list Graphics # List settings in a section +settings_search shadow # Search by pattern +settings_get Graphics WindowWidth # Get a specific value +settings_set Graphics WindowWidth 1920 # Change a value +settings_save # Save to disk +settings_reload # Reload from disk +settings_reset # Reset everything to defaults +``` + +--- + +## Settings by Category + +### Graphics + +| Key | Default | Description | +|-----|---------|-------------| +| `WindowWidth` | 1280 | Window width in pixels | +| `WindowHeight` | 720 | Window height in pixels | +| `Fullscreen` | false | Fullscreen mode | +| `VSync` | true | Vertical sync | +| `AntiAliasing` | 4 | MSAA sample count (1, 2, 4, 8) | +| `ShadowQuality` | 2 | 0=Off, 1=Low, 2=Medium, 3=High | +| `RenderScale` | 1.0 | Internal resolution scale (0.5–2.0) | +| `HDR` | false | High dynamic range rendering | + +### Rendering + +| Key | Default | Description | +|-----|---------|-------------| +| `RenderPath` | 1 | 0=Forward, 1=Deferred, 2=Forward+, 3=Clustered | +| `QualityPreset` | 2 | 0=Low, 1=Medium, 2=High, 3=Ultra, 4=Custom | +| `MaxTextureSize` | 2048 | Maximum texture dimension | +| `AnisotropicFiltering` | true | Enable anisotropic filtering | +| `AnisotropyLevel` | 16 | Anisotropy level (1–16) | +| `Shadows` | true | Enable shadow rendering | +| `ShadowMapSize` | 2048 | Shadow map resolution | +| `CascadeCount` | 3 | Cascaded shadow map splits | +| `Bloom` | true | Enable bloom effect | +| `SSAO` | false | Screen-space ambient occlusion | +| `TAA` | false | Temporal anti-aliasing | +| `MotionBlur` | false | Motion blur effect | +| `FrustumCulling` | true | Frustum culling optimization | +| `OcclusionCulling` | false | Hardware occlusion queries | +| `LevelOfDetail` | true | LOD system | +| `MaxDrawCalls` | 1000 | Draw call budget | +| `WireframeMode` | false | Wireframe rendering | +| `DebugMode` | false | Render debug overlays | +| `EnableGPUTiming` | false | GPU timing queries | + +### Post-Processing — Bloom + +| Key | Default | Description | +|-----|---------|-------------| +| `BloomEnabled` | true | Enable bloom | +| `BloomThreshold` | 1.0 | Brightness threshold | +| `BloomIntensity` | 1.0 | Bloom strength | +| `BloomRadius` | 1.0 | Bloom spread | +| `BloomSoftKnee` | 0.5 | Soft knee falloff | +| `BloomIterations` | 6 | Blur iterations (quality) | + +### Post-Processing — Tone Mapping + +| Key | Default | Description | +|-----|---------|-------------| +| `ToneMappingOperator` | 4 | 0=None, 1=Reinhard, 2=ReinhardJodie, 3=Uncharted2, 4=ACES, 5=AgX, 6=FilmicALU | +| `Exposure` | 1.0 | Exposure multiplier | +| `Gamma` | 2.2 | Display gamma | +| `WhitePoint` | 11.2 | White point for tonemapping | + +### Post-Processing — Color Grading + +| Key | Default | Description | +|-----|---------|-------------| +| `ColorGradingEnabled` | false | Enable color grading | +| `Temperature` | 0.0 | Color temperature shift | +| `Tint` | 0.0 | Tint shift | +| `Contrast` | 1.0 | Contrast multiplier | +| `Brightness` | 0.0 | Brightness offset | +| `Saturation` | 1.0 | Saturation multiplier | + +### SSAO + +| Key | Default | Description | +|-----|---------|-------------| +| `Enabled` | false | Enable SSAO | +| `Radius` | 0.5 | Sample radius (world units) | +| `Intensity` | 1.0 | Occlusion strength | +| `SampleCount` | 16 | Number of samples | +| `Bias` | 0.025 | Depth bias to prevent self-occlusion | +| `Blur` | true | Blur the AO buffer | + +### SSR (Screen-Space Reflections) + +| Key | Default | Description | +|-----|---------|-------------| +| `Enabled` | false | Enable SSR | +| `MaxDistance` | 100.0 | Maximum trace distance | +| `MaxSteps` | 32 | Maximum ray-march steps | +| `Thickness` | 0.5 | Surface thickness | +| `FadeStart` | 80.0 | Fade start distance | +| `FadeEnd` | 100.0 | Fade end distance | + +### Volumetric Lighting + +| Key | Default | Description | +|-----|---------|-------------| +| `Enabled` | false | Enable volumetrics | +| `SampleCount` | 32 | Ray-march samples | +| `Scattering` | 0.1 | Scattering coefficient | +| `Extinction` | 0.01 | Extinction coefficient | +| `Anisotropy` | 0.3 | Henyey-Greenstein anisotropy (−1 to 1) | + +### TAA (Temporal Anti-Aliasing) + +| Key | Default | Description | +|-----|---------|-------------| +| `Enabled` | true | Enable TAA | +| `Quality` | 2 | 0=Low, 1=Medium, 2=High, 3=Ultra | +| `JitterPattern` | 0 | 0=Halton2,3, 1=BlueNoise, 2=Uniform8x, 3=InterleavedGradient | +| `HistoryBlendFactor` | 0.9 | How much to blend with previous frame | +| `Sharpness` | 0.0 | Post-TAA sharpening | + +### Motion Blur + +| Key | Default | Description | +|-----|---------|-------------| +| `Enabled` | false | Enable motion blur | +| `Type` | 2 | 0=CameraOnly, 1=PerObject, 2=Combined | +| `Intensity` | 0.5 | Blur strength | +| `SampleCount` | 8 | Blur samples | +| `MaxBlurRadius` | 32.0 | Maximum blur radius in pixels | + +### Dynamic Quality Scaler + +| Key | Default | Description | +|-----|---------|-------------| +| `Enabled` | true | Enable dynamic quality scaling | +| `TargetFrameTimeMs` | 16.67 | Target frame time (60 FPS) | +| `MinRenderScale` | 0.5 | Minimum render scale | +| `MaxRenderScale` | 1.0 | Maximum render scale | + +### Audio + +| Key | Default | Description | +|-----|---------|-------------| +| `MasterVolume` | 1.0 | Master volume (0.0–1.0) | +| `SFXVolume` | 0.8 | Sound effects volume | +| `MusicVolume` | 0.6 | Music volume | +| `VoiceVolume` | 1.0 | Voice/dialogue volume | +| `MuteOnFocusLoss` | true | Mute when window loses focus | + +### Audio Extended + +| Key | Default | Description | +|-----|---------|-------------| +| `DopplerScale` | 1.0 | Doppler effect strength | +| `DistanceScale` | 1.0 | Distance attenuation scale | +| `Enable3D` | true | 3D spatial audio | +| `EnableReverb` | false | Reverb processing | +| `MaxSources` | 32 | Maximum concurrent audio sources | + +### Controls + +| Key | Default | Description | +|-----|---------|-------------| +| `MouseSensitivity` | 1.0 | Mouse look sensitivity | +| `InvertMouse` | false | Invert Y axis | +| `MouseDeadZone` | 0.0 | Dead zone threshold | +| `RawMouseInput` | false | Use raw mouse input (bypasses OS acceleration) | +| `MouseAcceleration` | false | Enable mouse acceleration | + +### Game + +| Key | Default | Description | +|-----|---------|-------------| +| `Difficulty` | "Normal" | Game difficulty level | +| `ShowFPS` | true | Show FPS counter | +| `ShowDebugInfo` | false | Show debug overlay | +| `FieldOfView` | 90.0 | Camera field of view (degrees) | + +### Physics + +| Key | Default | Description | +|-----|---------|-------------| +| `GravityX` / `GravityY` / `GravityZ` | 0 / −20 / 0 | World gravity vector | +| `FixedTimestep` | 0.016667 | Physics step (60 Hz) | +| `MaxSubSteps` | 4 | Maximum sub-steps per frame | +| `DefaultFriction` | 0.5 | Default body friction | +| `DefaultRestitution` | 0.3 | Default body bounciness | +| `DebugDraw` | false | Physics debug visualization | + +### AI + +| Key | Default | Description | +|-----|---------|-------------| +| `DetectionRange` | 30.0 | AI detection range (units) | +| `AttackRange` | 15.0 | AI attack range | +| `MoveSpeed` | 5.0 | AI movement speed | +| `TurnSpeed` | 180.0 | AI turn speed (degrees/sec) | +| `Accuracy` | 0.7 | AI aiming accuracy (0.0–1.0) | +| `ReactionTime` | 0.3 | AI reaction delay (seconds) | + +### Player + +| Key | Default | Description | +|-----|---------|-------------| +| `MaxHealth` | 100.0 | Maximum health | +| `MaxArmor` | 100.0 | Maximum armor | +| `MoveSpeed` | 5.0 | Walk speed | +| `JumpHeight` | 3.0 | Jump height | +| `SprintMultiplier` | 2.0 | Sprint speed multiplier | +| `CrouchMultiplier` | 0.5 | Crouch speed multiplier | + +### Camera + +| Key | Default | Description | +|-----|---------|-------------| +| `DefaultFov` | 90.0 | Default field of view | +| `ZoomedFov` | 45.0 | ADS / zoomed FOV | +| `NearPlane` | 0.1 | Near clip plane | +| `FarPlane` | 1000.0 | Far clip plane | +| `SmoothMovement` | true | Smooth camera interpolation | + +### Network + +| Key | Default | Description | +|-----|---------|-------------| +| `ServerPort` | 27015 | Default server port | +| `MaxClients` | 32 | Maximum connected clients | +| `ConnectionTimeout` | 10.0 | Connection timeout (seconds) | +| `ReplicationRate` | 20.0 | Network updates per second | +| `EnableCompression` | false | Compress network packets | +| `EnableEncryption` | false | Encrypt network packets | +| `SimulatedLatencyMs` | 0.0 | Simulated latency for testing | +| `SimulatedPacketLoss` | 0.0 | Simulated packet loss (0.0–1.0) | + +### Scripting + +| Key | Default | Description | +|-----|---------|-------------| +| `HotReloadEnabled` | true | Auto-reload scripts on file change | +| `HotReloadPollInterval` | 1.0 | File watch interval (seconds) | +| `ExecutionTimeoutMs` | 100.0 | Script execution timeout | +| `MaxCallStackDepth` | 64 | Maximum recursion depth | +| `MaxScriptMemoryMB` | 64 | Script memory limit | + +### Animation + +| Key | Default | Description | +|-----|---------|-------------| +| `DefaultBlendTime` | 0.2 | Animation blend duration | +| `IKSolverIterations` | 10 | IK solver iterations | +| `MaxActiveMontages` | 4 | Maximum concurrent montages | +| `EnableRootMotion` | true | Enable root motion | +| `CompressionQuality` | 2 | 0=None, 1=Low, 2=Medium, 3=High | + +### Editor + +| Key | Default | Description | +|-----|---------|-------------| +| `GridSize` | 1.0 | Editor grid spacing | +| `SnapToGrid` | true | Snap objects to grid | +| `ShowGrid` | true | Show grid in viewport | +| `GizmoScale` | 1.0 | Gizmo handle size | +| `AutosaveEnabled` | true | Autosave scenes | +| `AutosaveIntervalSeconds` | 300 | Autosave interval (seconds) | +| `UndoHistorySize` | 100 | Undo stack depth | + +### Logging + +| Key | Default | Description | +|-----|---------|-------------| +| `GlobalLevel` | "Info" | Log level: Trace, Debug, Info, Warn, Error, Fatal, Off | +| `StackTraceLevel` | "Error" | Include stack traces at this level and above | + +Per-category overrides (set to empty string to inherit `GlobalLevel`): + +`CoreLevel`, `GraphicsLevel`, `PhysicsLevel`, `AudioLevel`, `AILevel`, `AnimationLevel`, `ECSLevel`, `NetworkLevel`, `InputLevel`, `ScriptingLevel`, `SceneLevel`, `SaveLevel`, `CinematicLevel`, `ProceduralLevel`, `EditorLevel`, `GameLevel` + +--- + +## Console Commands + +### Engine Core + +| Command | Usage | Description | +|---------|-------|-------------| +| `help` | `help [command]` | List commands or show help for a specific command | +| `clear` | `clear` | Clear the console | +| `version` | `version` | Show engine version | +| `engine_subsystems` | `engine_subsystems` | List all active subsystems and their status | +| `metrics` | `metrics` | Comprehensive system metrics | +| `asset_list` | `asset_list` | List all loaded assets | + +### Settings + +| Command | Usage | Description | +|---------|-------|-------------| +| `settings_get` | `settings_get
` | Read a setting | +| `settings_set` | `settings_set
` | Change a setting at runtime | +| `settings_save` | `settings_save` | Write settings to disk | +| `settings_reload` | `settings_reload` | Reload from disk | +| `settings_reset` | `settings_reset` | Reset all to defaults | +| `settings_list` | `settings_list [section]` | List settings | +| `settings_search` | `settings_search ` | Search settings | + +### Rendering + +| Command | Usage | Description | +|---------|-------|-------------| +| `render_stats` | `render_stats` | Show draw calls, triangles, batches | +| `render_quality` | `render_quality ` | Quality preset | +| `wireframe` | `wireframe ` | Toggle wireframe | +| `vsync` | `vsync ` | Toggle VSync | +| `shadows` | `shadows ` | Toggle shadows | +| `hdr` | `hdr ` | Toggle HDR | +| `exposure` | `exposure ` | Set exposure | +| `screenshot` | `screenshot` | Capture screenshot | + +### Shaders + +| Command | Usage | Description | +|---------|-------|-------------| +| `shader_list` | `shader_list` | List loaded shaders | +| `shader_reload` | `shader_reload` | Reload all shaders from disk | +| `shader_debug` | `shader_debug ` | Debug shader compilation | + +### Textures & Materials + +| Command | Usage | Description | +|---------|-------|-------------| +| `tex_list` | `tex_list` | List loaded textures | +| `tex_info` | `tex_info ` | Texture details | +| `tex_quality` | `tex_quality ` | Texture quality | +| `tex_memory` | `tex_memory ` | Texture memory budget | +| `mat_list` | `mat_list` | List loaded materials | +| `mat_info` | `mat_info ` | Material details | + +### Physics + +| Command | Usage | Description | +|---------|-------|-------------| +| `physics_metrics` | `physics_metrics` | Physics performance stats | +| `physics_list` | `physics_list` | List all physics bodies | +| `physics_body_info` | `physics_body_info ` | Body details | +| `physics_gravity` | `physics_gravity ` | Set gravity | +| `physics_debug` | `physics_debug ` | Toggle debug draw | +| `physics_pause` | `physics_pause` | Pause/resume simulation | +| `physics_timestep` | `physics_timestep ` | Set fixed timestep | +| `physics_raycast` | `physics_raycast` | Cast a test ray | +| `physics_create` | `physics_create ` | Create a body | +| `physics_remove` | `physics_remove ` | Remove a body | +| `physics_force` | `physics_force ` | Apply force | +| `physics_impulse` | `physics_impulse ` | Apply impulse | +| `physics_reset` | `physics_reset` | Reset physics world | + +### Audio + +| Command | Usage | Description | +|---------|-------|-------------| +| `audio_master_volume` | `audio_master_volume <0.0-1.0>` | Master volume | +| `audio_sfx_volume` | `audio_sfx_volume <0.0-1.0>` | SFX volume | +| `audio_music_volume` | `audio_music_volume <0.0-1.0>` | Music volume | +| `audio_3d` | `audio_3d ` | Toggle 3D audio | +| `audio_play_test` | `audio_play_test [3d]` | Play test sound | +| `audio_stop_all` | `audio_stop_all` | Stop all sounds | +| `audio_list` | `audio_list` | List loaded sounds | +| `audio_metrics` | `audio_metrics` | Audio stats | +| `audio_doppler` | `audio_doppler ` | Set Doppler scale | + +### Time of Day & Weather + +| Command | Usage | Description | +|---------|-------|-------------| +| `time_set` | `time_set <0-24>` | Set time (0=midnight, 12=noon) | +| `time_speed` | `time_speed ` | Time progression speed | +| `time_info` | `time_info` | Current time info | +| `weather` | `weather ` | Set weather | + +### Save System + +| Command | Usage | Description | +|---------|-------|-------------| +| `save_list` | `save_list` | List save slots | +| `save_info` | `save_info ` | Save slot details | +| `quicksave` | `quicksave` | Quick save | +| `quickload` | `quickload` | Quick load | + +### Modules & Hot-Reload + +| Command | Usage | Description | +|---------|-------|-------------| +| `module_info` | `module_info` | Show loaded module info | +| `module_reload` | `module_reload [name]` | Hot-reload a module | +| `module.hotreload.enable` | `module.hotreload.enable` | Enable auto hot-reload | +| `module.hotreload.disable` | `module.hotreload.disable` | Disable auto hot-reload | +| `module.hotreload.status` | `module.hotreload.status` | Show hot-reload status | + +### Fault Isolation + +| Command | Usage | Description | +|---------|-------|-------------| +| `fault.status` | `fault.status` | Show fault status for all subsystems | +| `fault.reset` | `fault.reset ` | Re-enable a faulted subsystem | +| `fault.reset_all` | `fault.reset_all` | Re-enable all faulted subsystems | +| `fault.autorecovery` | `fault.autorecovery ` | Toggle auto-recovery | + +--- + +## FPS Game Module Commands + +These commands are available when the SparkGameFPS module is loaded. + +### Gameplay + +| Command | Usage | Description | +|---------|-------|-------------| +| `god` | `god` | Toggle god mode | +| `noclip` | `noclip` | Toggle noclip | +| `player_tp` | `player_tp ` | Teleport player | +| `spawn` | `spawn ` | Spawn an object | +| `game_timescale` | `game_timescale ` | Set time scale | +| `game_stats` | `game_stats` | Performance statistics | +| `hud` | `hud [on\|off]` | Toggle HUD | + +### Game Modes + +| Command | Usage | Description | +|---------|-------|-------------| +| `gamemode` | `gamemode ` | Switch mode | +| `gamemode_info` | `gamemode_info` | Current mode info | + +Available modes: `freeplay`, `deathmatch`, `tdm`, `ctf`, `domination`, `elimination`, `gungame`, `koth`, `survival` + +### Inventory & Quests + +| Command | Usage | Description | +|---------|-------|-------------| +| `inventory` | `inventory` | Show inventory | +| `give` | `give [count]` | Give item | +| `quest_list` | `quest_list` | Active quests | +| `quest_start` | `quest_start ` | Start quest | +| `quest_all` | `quest_all` | List all quests | + +### Waves & Combat + +| Command | Usage | Description | +|---------|-------|-------------| +| `wave_start` | `wave_start` | Start survival waves | +| `wave_status` | `wave_status` | Current wave info | +| `wave_skip` | `wave_skip [number]` | Skip to wave | +| `wave_difficulty` | `wave_difficulty <1.0-3.0>` | Difficulty scale | + +### Progression + +| Command | Usage | Description | +|---------|-------|-------------| +| `level` | `level` | Show level and XP | +| `xp` | `xp ` | Award XP | +| `loot_status` | `loot_status` | Loot system info | +| `powerup` | `powerup ` | Spawn power-up (speed, damage, shield, ammo, xp, invis) | + +### Cinematics & Replay + +| Command | Usage | Description | +|---------|-------|-------------| +| `seq_list` | `seq_list` | List sequences | +| `seq_play` | `seq_play ` | Play sequence | +| `seq_stop` | `seq_stop [name]` | Stop sequence | +| `replay_start` | `replay_start` | Start recording | +| `replay_stop` | `replay_stop` | Stop recording | +| `replay_save` | `replay_save ` | Save replay | +| `replay_load` | `replay_load ` | Load replay | +| `replay_play` | `replay_play` | Play replay | +| `replay_speed` | `replay_speed ` | Playback speed | + +### Networking + +| Command | Usage | Description | +|---------|-------|-------------| +| `net_host` | `net_host [port] [max_clients]` | Host a server | +| `net_connect` | `net_connect
[port]` | Connect to server | +| `net_disconnect` | `net_disconnect` | Disconnect | +| `net_status` | `net_status` | Connection status | +| `net_stats` | `net_stats` | Network statistics | + +--- + +## Console Variables (CVars) + +SparkEngine includes a typed CVar system for runtime-tweakable variables. CVars are separate from settings — they are registered in code and accessed via the CVar registry. + +### CVar Flags + +| Flag | Meaning | +|------|---------| +| `None` | Normal read/write | +| `ReadOnly` | Cannot be modified at runtime | +| `Cheat` | Only available when cheats are enabled | +| `Save` | Persisted to disk | + +### Using CVars in C++ + +```cpp +#include "Utils/ConsoleVariable.h" + +// Register a CVar +static CVar cv_fov("r.fov", 90.0f, CVarFlags::Save, "Field of view"); + +// Read +float fov = cv_fov.Get(); + +// Write +cv_fov.Set(110.0f); + +// With range constraint +static CVar cv_vol("audio.volume", 1.0f, CVarFlags::Save, "Volume", 0.0f, 1.0f); +``` + +--- + +## See Also + +- [Getting Started](Getting-Started) — Build and run the engine +- [Quick-Start Tutorial](Quick-Start-Tutorial) — Your first 10 minutes +- [Performance Tips](Performance-Tips) — Optimization guide +- [Troubleshooting](Troubleshooting) — Common issues and fixes +- [SparkConsole](SparkConsole) — Standalone console application diff --git a/wiki/Editor-Walkthrough.md b/wiki/Editor-Walkthrough.md new file mode 100644 index 000000000..a4a001dac --- /dev/null +++ b/wiki/Editor-Walkthrough.md @@ -0,0 +1,375 @@ +# Editor Walkthrough + +A practical, hands-on guide to the SparkEditor. This page covers day-to-day workflows rather than exhaustive API details. For the full panel reference, see [SparkEditor](SparkEditor). + +--- + +## Opening the Editor + +Press **F1** while the engine is running. The editor is an ImGui overlay that runs on top of the game viewport. Press **F1** again to close it. + +The editor requires `ENABLE_EDITOR=ON` at build time (default on Windows). + +--- + +## Default Layout + +When you first open the editor, 7 core panels are visible: + +| Panel | Position | What it does | +|-------|----------|--------------| +| **Scene View** | Center | 3D viewport with editor gizmos and camera controls | +| **Hierarchy** | Left | Tree view of all entities in the scene | +| **Inspector** | Right | Property editor for the selected entity | +| **Asset Browser** | Bottom | Project file browser with thumbnails | +| **Console** | Bottom | Log output, command input, and filtering | +| **Game View** | Tab (center) | In-game camera preview with HUD | +| **Profiler** | Tab (bottom) | Real-time performance graphs | + +All panels can be dragged, docked, resized, or closed. Reopen any panel from the **Window** menu. + +--- + +## Scene View Navigation + +The Scene View is your primary 3D viewport. + +| Input | Action | +|-------|--------| +| Right-click + drag | Orbit camera | +| Middle-click + drag | Pan camera | +| Scroll wheel | Zoom in/out | +| Click entity | Select it | +| W | Translate gizmo (move) | +| E | Rotate gizmo | +| R | Scale gizmo | + +### Render Modes + +The Scene View toolbar lets you switch between render modes: + +- **Shaded** — Full PBR rendering (default) +- **Wireframe** — Wireframe overlay +- **Unlit** — No lighting, diffuse color only +- **Normals** — Visualize surface normals + +### Grid and Snapping + +- The grid is visible by default (toggle in Editor settings) +- **Snap to grid** is enabled by default with 1.0 unit spacing +- Change grid size in `settings.ini` under `[Editor]`: `GridSize = 0.5` + +--- + +## Working with Entities + +### Creating Entities + +- **Hierarchy panel** → Right-click → "Create Entity" +- Or use the **Object Placement** panel (Window → Object Placement) for advanced placement with brush, line, grid, and scatter modes + +### Selecting Entities + +- Click in the **Scene View** to select +- Or click in the **Hierarchy** panel +- The selected entity highlights in the viewport and the Inspector shows its components + +### Editing Components + +The **Inspector** panel displays all components attached to the selected entity: + +- **Transform** — Position, rotation, scale (always present) +- **MeshRenderer** — 3D mesh and material +- **RigidBody** — Physics body settings +- **Light** — Point, directional, or spot light +- **AudioSource** — Sound emitter +- **Camera** — Camera parameters +- And 70+ more component types + +Click **Add Component** at the bottom of the Inspector to attach new components. + +### Undo / Redo + +All editor operations support undo/redo: + +- **Ctrl+Z** — Undo +- **Ctrl+Y** — Redo +- Open the **Undo History** panel to see the full command stack and jump to any point + +--- + +## Content Creation Panels + +### Material Editor + +Open from **Window → Material Editor**. Edit PBR material properties: + +- **Albedo** — Base color and texture +- **Metallic / Roughness** — PBR parameters with texture slots +- **Normal Map** — Surface detail +- **Emission** — Self-illumination +- **AO** — Ambient occlusion + +Drag textures from the Asset Browser into texture slots. The live preview sphere updates in real-time. + +### Particle Editor + +Open from **Window → Particle Editor**. Configure GPU particle emitters: + +- **Emission** — Rate, burst count, shape (point, sphere, cone, box, circle) +- **Appearance** — Color gradient over lifetime, size curve +- **Physics** — Gravity, drag, collision +- **Sub-emitters** — Particles that spawn particles +- **Trails** — Ribbon trail rendering + +### Sprite & Tilemap Editors + +For 2D games: + +- **Sprite Editor** — Configure source rects, pivots, pixels-per-unit, sorting layers +- **Sprite Animation Editor** — Frame-based animation with timeline, onion skinning, and sprite sheet auto-slice +- **Tilemap Editor** — Paint tiles with brush, fill, and rectangle tools. Supports collision tiles, layers, and auto-tiling + +### Terrain Editor + +Open from **Window → Terrain Editor**. Sculpt heightmap terrain: + +- Paint height with raise/lower/smooth/flatten brushes +- Paint textures with blending layers +- Integrated with the physics system for collision + +--- + +## Gameplay & Design Panels + +### Weapon Editor + +Open from **Window → Weapon Editor**. Balance weapons by editing stats: + +- Damage, fire rate, magazine size, reload time +- Accuracy, range, recoil pattern +- DPS chart for quick comparison +- Side-by-side weapon comparison table + +### AI Editor & Debug + +- **AI Editor** — Create behavior tree templates with Selector, Sequence, Action, Condition, Decorator, and Parallel nodes +- **AI Debug** — Live-inspect AI agents during play mode. Shows blackboard variables, BT execution trace, perception ranges, and nav paths + +### Dialogue Editor + +Open from **Window → Dialogue Editor**. Author branching dialogue trees: + +- Create text, choice, branch, event, and end nodes +- Assign speakers, animations, and voice clips +- Set conditions on choices (requires variables set in the Condition Editor) + +### Cinematic Sequencer + +Open from **Window → Cinematic Sequencer**. Create cutscenes: + +- Add tracks (camera, actor, audio, event) +- Place keyframes on the timeline +- Scrub the timeline for preview +- Export to JSON + +### Event Response Panel + +Open from **Window → Event Response**. Build "When/If/Then" gameplay rules without code: + +- **When** — Choose a trigger event type +- **If** — Add conditions (AND/OR groups) +- **Then** — Define actions to execute + +--- + +## Physics Panels + +### Physics 3D + +Open from **Window → Physics 3D**. Configure the Jolt Physics world: + +- Set gravity, timestep, substep count +- Toggle debug visualization (wireframes, AABBs, contacts, constraints) +- Quick-add primitive shapes (box, sphere, capsule, cylinder) +- Physics material presets +- Raycast testing tool + +### Physics 2D + +Open from **Window → Physics 2D**. For 2D physics: + +- World gravity settings +- Collision layer matrix editor +- Body inspector +- Spatial hash grid visualization + +--- + +## Audio + +### Audio Mixer + +Open from **Window → Audio Mixer**: + +- Master / SFX / Music volume sliders +- Mix bus hierarchy with VU meters +- DSP effects (reverb, EQ, compressor) +- Active sound monitoring +- Sound bank browser +- Reverb zone configuration + +--- + +## Project Management + +### Project Settings + +Open from **Window → Project Settings**. Tabbed categories for all engine settings: + +- Graphics, Rendering, Post-Processing, Audio, Controls +- Physics, AI, Player, Gameplay, Camera +- Network, Scripting, Animation, Editor, Logging + +Changes apply at runtime and can be saved to `settings.ini`. + +### Build & Cook + +Open from **Window → Build & Cook**. Package your game: + +- Select build profile (Debug / Development / Release / Shipping) +- Choose target platform +- Configure asset cooking (texture, audio, mesh compression) +- One-click build with progress monitoring + +### Game Module Selector + +Open from **Window → Game Module Selector**: + +- Scan for available game module DLLs +- Toggle modules active/inactive +- Generate `spark.modules.json` manifest + +--- + +## Debugging Panels + +### Debug Visualizer + +Open from **Window → Debug Visualizer**. Toggle overlays: + +- Physics (colliders, AABBs, contacts, raycasts, velocities) +- Navigation (navmesh, paths, agents) +- Audio (listener position, source ranges) +- Camera and light debug +- Performance overlays (FPS, draw calls, triangle count) + +### Scene Statistics + +Open from **Window → Scene Statistics**: + +- Entity counts and component breakdowns +- Rendering statistics (draw calls, triangles, batches) +- Physics body counts +- Memory usage +- Performance graphs with history + +### Event Monitor + +Open from **Window → Event Monitor**. Watch the EventBus in real-time: + +- Filter by event type or category +- Color-coded by category +- Useful for debugging event-driven systems + +### Coroutine Debug + +Open from **Window → Coroutine Debug**. Monitor active coroutines: + +- Status (running, suspended, completed, failed) +- Elapsed time and wait states +- Cancel coroutines individually + +--- + +## Play Mode + +The **Play Mode Toolbar** (top of editor) controls simulation: + +| Button | Action | +|--------|--------| +| **Play** | Start simulation | +| **Pause** | Freeze simulation | +| **Stop** | Reset to editor state | +| **Step** | Advance one frame | + +### Time Scale + +The toolbar includes a time-scale slider with presets: + +- **0.25x** — Quarter speed (useful for debugging physics) +- **0.5x** — Half speed +- **1x** — Normal +- **2x / 4x** — Fast-forward + +### Subsystem Toggles + +During play mode, you can selectively enable/disable: + +- Physics, AI, Audio, Animation, Scripting, Particles + +This is useful for isolating bugs — disable everything except the system you are debugging. + +--- + +## Collaborative Editing + +SparkEngine supports multi-user editing sessions: + +1. Open **Window → Collaboration** +2. One user clicks **Host** to start a session +3. Others click **Join** and enter the host address +4. Entity locks prevent two users from editing the same object simultaneously +5. The activity log shows who is editing what + +See [Collaborative Editing](Collaborative-Editing) for details. + +--- + +## Customization + +### Themes + +The editor uses a customizable theme system. Default themes are applied via `EditorTheme.cpp`. Custom themes can override colors, spacing, and font sizes. + +### Panel Visibility + +- All 56 panels are accessible from the **Window** menu +- Drag panels to rearrange the layout +- Layouts persist between sessions + +--- + +## Keyboard Reference + +| Shortcut | Action | +|----------|--------| +| F1 | Toggle editor | +| F3 | Toggle FPS stats | +| ` (Backtick) | Toggle console | +| W | Translate gizmo | +| E | Rotate gizmo | +| R | Scale gizmo | +| Ctrl+Z | Undo | +| Ctrl+Y | Redo | +| Ctrl+S | Save scene | +| Delete | Delete selected entity | + +--- + +## See Also + +- [SparkEditor](SparkEditor) — Full panel reference and architecture details +- [Artist Workflow Guide](Artist-Workflow-Guide) — Asset creation workflows +- [Quick-Start Tutorial](Quick-Start-Tutorial) — Your first 10 minutes +- [Configuration Reference](Configuration-Reference) — All settings and console commands diff --git a/wiki/FAQ.md b/wiki/FAQ.md new file mode 100644 index 000000000..81d1196f2 --- /dev/null +++ b/wiki/FAQ.md @@ -0,0 +1,278 @@ +# Frequently Asked Questions + +Common questions about SparkEngine — what it is, who it's for, and how to get started. + +--- + +## General + +### What is SparkEngine? + +SparkEngine is a free, open-source 3D game engine written in C++23. It started as an FPS engine and is evolving into a general-purpose engine supporting FPS, RPG, MMO, open-world, racing, platformer, and RTS genres. It ships with DirectX 11 rendering, Jolt Physics, XAudio2 spatial audio, AngelScript scripting, an EnTT ECS, and an ImGui-based visual editor. + +### Is SparkEngine free? + +Yes. SparkEngine is licensed under the [MIT License](https://github.com/Krilliac/SparkEngine/blob/master/LICENSE) — no royalties, no strings attached. You can use it for commercial games. + +### What platforms does SparkEngine support? + +| Platform | Status | +|----------|--------| +| Windows 10+ | Primary (fully supported) | +| Linux x64 | Experimental (GCC 13+, Clang 17+) | +| macOS | Experimental (Apple Clang) | + +Windows is the primary development platform. Linux and macOS builds run in CI and are usable but may have rough edges. + +### What genres can I make with SparkEngine? + +SparkEngine ships with example game modules for FPS, platformer, racing, RPG, RTS, and MMO. The ECS architecture is genre-agnostic — you can build any type of game. The engine includes systems for weapons, vehicles, inventory, quests, dialogue, AI, networking, and more. + +### How does SparkEngine compare to Unity / Unreal / Godot? + +SparkEngine is smaller and earlier in development than those engines. Key differences: + +- **Open-source C++23** — You have full source access and can modify anything. No black-box runtime. +- **No editor lock-in** — Game logic lives in C++ modules or AngelScript scripts, not in a proprietary project format. +- **MMO-ready architecture** — Built-in area server architecture, seamless world streaming, and collaborative editing (inspired by HeroEngine). +- **Lightweight** — The full engine compiles in 2–5 minutes. No gigabyte downloads. +- **Trade-off** — Fewer ready-made assets, smaller community, and less polish than mature engines. + +### Do I need to know C++ to use SparkEngine? + +C++ is the primary language, but you have options: + +- **AngelScript** — A C-like scripting language with hot-reload. Write gameplay logic without recompiling the engine. +- **Visual Scripting** — A node-based visual scripting system that compiles to AngelScript. No code required. +- **C++ Modules** — For full engine access, write a game module in C++23. + +Artists and level designers can use the editor without writing code at all — see the [Artist Workflow Guide](Artist-Workflow-Guide). + +--- + +## Building & Running + +### What do I need to build SparkEngine? + +- A C++23 compiler: MSVC v143+ (VS 2022), GCC 13+, or Clang 17+ +- CMake 3.25+ +- Git (for submodules) + +See [Getting Started](Getting-Started) for full platform-specific instructions. + +### How long does it take to build? + +A clean Release build takes 2–5 minutes on a modern machine with 8+ cores. Incremental builds after small changes take seconds. + +### Can I build without a GPU? + +Yes. The engine has multiple fallback paths: + +| Backend | GPU-less fallback | +|---------|-------------------| +| D3D11 | WARP (Windows software rasterizer) | +| D3D12 | WARP | +| Vulkan | Lavapipe (Mesa) | +| OpenGL | llvmpipe (Mesa) | +| None | NullRHIDevice (headless, no rendering) | + +Use `-headless` to run with no graphics at all (for dedicated servers or automated testing). + +### How do I run the engine on Linux without a display? + +Use Xvfb (virtual framebuffer) with Mesa software rendering: + +```bash +sudo apt-get install -y xvfb libgl1-mesa-dri +Xvfb :99 -screen 0 1024x768x24 & +DISPLAY=:99 LIBGL_ALWAYS_SOFTWARE=1 ./SparkEngine +``` + +### Can I build just the engine without the editor? + +Yes. Use the `minimal` CMake preset or disable individual features: + +```bash +cmake --preset minimal # Core engine only +cmake -B build -DENABLE_EDITOR=OFF # Everything except editor +``` + +### What are the command-line arguments? + +| Argument | Description | +|----------|-------------| +| `-headless` | No graphics or audio (dedicated server mode) | +| `-game ` | Load a specific game module DLL/SO | +| `-window-size WxH` | Override window resolution (e.g., `1920x1080`) | +| `-test-frames N` | Run N frames then exit (for benchmarking) | +| `-fullscreen` | Start in fullscreen mode | +| `-console` / `-noconsole` | Force-enable or disable the debug console | +| `-scene ` | Load a specific scene on startup | + +--- + +## Editor + +### How do I open the editor? + +Press **F1** while the engine is running, or build with `ENABLE_EDITOR=ON` (default on Windows). The editor is an ImGui-based overlay with 56 panels. + +### What panels does the editor have? + +The editor ships with 56 panels covering scene editing, asset management, physics, gameplay, audio, scripting, profiling, and more. The 7 core panels shown by default are: + +- **Scene View** — 3D viewport with gizmos +- **Hierarchy** — Scene graph tree +- **Inspector** — Component property editor +- **Asset Browser** — File browser with thumbnails +- **Console** — Command and log panel +- **Game View** — In-game preview +- **Profiler** — Performance metrics + +All other panels are available from the **Window** menu. See [Editor Walkthrough](Editor-Walkthrough) for a practical guide. + +### Can multiple people edit a scene at the same time? + +Yes. SparkEngine supports collaborative multi-user editing sessions (inspired by HeroEngine). One user hosts, others join. Entity locks prevent conflicts. See [Collaborative Editing](Collaborative-Editing). + +--- + +## Gameplay & Scripting + +### How do I create a new game? + +Create a **game module** — a DLL/SO that implements the `IModule` interface. The engine auto-discovers modules in the `GameModules/` directory. See [Creating a Game Module](Creating-a-Game-Module) for a step-by-step guide, or [Making Your First Game](Making-Your-First-Game) for a tutorial. + +### What scripting language does SparkEngine use? + +[AngelScript](Scripting-with-AngelScript) — a statically-typed scripting language with C-like syntax. Scripts hot-reload automatically when you save changes to disk (no recompile needed). + +### Does SparkEngine support visual scripting? + +Yes. The [Visual Scripting](Visual-Scripting) panel provides a node-based editor that compiles to AngelScript under the hood. You can mix visual scripts with hand-written AngelScript. + +### How does the ECS work? + +SparkEngine uses [EnTT](https://github.com/skypjack/entt) for its Entity Component System. Entities are lightweight IDs, components are plain data structs, and systems operate on component groups. The engine provides 79 built-in component types and 67 systems. See [Entity Component System](Entity-Component-System). + +### How do I add multiplayer to my game? + +The engine includes a UDP client/server networking stack with entity replication, client-side prediction, and lag compensation. Start with the [Multiplayer Quick Start](Multiplayer-Quick-Start) guide, then see [Networking](Networking) for details. + +--- + +## Graphics + +### What rendering backends are available? + +| Backend | Status | Platform | +|---------|--------|----------| +| DirectX 11 | Primary | Windows | +| DirectX 12 | Experimental | Windows | +| Vulkan | Experimental | Windows, Linux | +| OpenGL 4.5 | Experimental | Windows, Linux, macOS | +| Metal | Experimental | macOS | +| NullRHI | Headless fallback | All | + +All backends implement the same [RHI Abstraction Layer](RHI-Abstraction-Layer). + +### What rendering features are supported? + +Forward, deferred, forward+, and clustered rendering pipelines. PBR materials, cascaded shadow maps, SSAO, SSR, volumetric fog, bloom, HDR tonemapping (ACES, Filmic, Reinhard, AgX), TAA/FXAA/MSAA, GPU particles, decals, image-based lighting, mesh shaders, GPU-driven rendering, and dynamic quality scaling. + +### Can I use ray tracing? + +DXR 1.1 ray tracing is available on the D3D12 backend (Windows, SM6.5+ GPU required). A hybrid ray tracing mode blends rasterization with selective ray-traced effects. See [DXR Raytracing](DXR-Raytracing) and [Hybrid Ray Tracing](Hybrid-Ray-Tracing). + +--- + +## Physics + +### What physics engine does SparkEngine use? + +[Jolt Physics](https://github.com/jrouwe/JoltPhysics) — a modern, high-performance physics engine. It supports rigid bodies, 15 collision shapes, 12 constraint types, character controllers, vehicles, ragdolls, cloth simulation, and multithreaded job dispatch. + +### Can I tune physics settings at runtime? + +Yes. Use console commands: + +``` +physics_gravity 0 -9.81 0 # Set gravity +physics_timestep 0.01667 # Set fixed timestep +physics_debug on # Toggle debug visualization +physics_metrics # Show performance stats +``` + +Or edit `[Physics]` in `settings.ini`. See [Configuration Reference](Configuration-Reference). + +--- + +## Audio + +### What audio backend does SparkEngine use? + +XAudio2 on Windows with miniaudio as a cross-platform fallback. The audio system supports 3D spatial audio, Doppler effects, distance attenuation, mix buses, DSP effects (reverb, EQ, compressor), and volume channels (master, SFX, music, voice). + +--- + +## Modding & Content + +### Does SparkEngine support mods? + +Yes. The [Mod System](Mod-System) handles mod discovery, load order, dependency checking, and enable/disable toggling. The editor includes a Modding Panel for managing mods. + +### What asset formats are supported? + +| Type | Formats | +|------|---------| +| 3D Models | FBX, glTF/GLB, OBJ | +| Textures | PNG, JPG, TGA, DDS, HDR | +| Audio | WAV, OGG, MP3, FLAC | +| Scenes | `.scene` (JSON-based) | + +See [Asset Pipeline](Asset-Pipeline) and [Asset Format Specifications](Asset-Format-Specifications). + +--- + +## Troubleshooting + +### The engine crashes on startup + +1. Check that your GPU supports DirectX 11 (Windows) or OpenGL 4.5 (Linux) +2. Update GPU drivers +3. Check `spark.log` for error messages +4. Try a Debug build for better error output +5. Try `-headless` to rule out graphics issues + +See [Troubleshooting](Troubleshooting) for a comprehensive list of known issues and fixes. + +### CI is failing on my PR + +Check which job failed: + +| Job | What it checks | +|-----|----------------| +| `check-format` | clang-format compliance | +| `build-linux-gcc` | GCC compilation + tests | +| `build-linux-clang` | Clang compilation + tests | +| `build-linux-asan` | Memory safety (ASan + UBSan) | +| `build-windows-vs2022` | MSVC compilation + tests | + +Jobs marked `continue-on-error` (VS2026, MinGW, macOS, clang-tidy) are warnings, not blockers. See [Contributing](Contributing) for the full CI overview. + +### Where do I get help? + +- [Troubleshooting](Troubleshooting) — Common issues and fixes +- [GitHub Issues](https://github.com/Krilliac/SparkEngine/issues) — Bug reports and feature requests +- Engine console: type `help` to list all commands, or `help ` for details + +--- + +## See Also + +- [Getting Started](Getting-Started) — Build and run the engine +- [Making Your First Game](Making-Your-First-Game) — Step-by-step game tutorial +- [Quick-Start Tutorial](Quick-Start-Tutorial) — Your first 10 minutes +- [Configuration Reference](Configuration-Reference) — All settings and commands +- [Editor Walkthrough](Editor-Walkthrough) — Practical editor guide +- [Performance Tips](Performance-Tips) — Optimization guide diff --git a/wiki/Home.md b/wiki/Home.md index 7a6383428..8f59af93c 100644 --- a/wiki/Home.md +++ b/wiki/Home.md @@ -33,10 +33,26 @@ Pre-built binaries are published on every commit to `master`: - [Linux Release (x64)](https://github.com/Krilliac/SparkEngine/releases/latest/download/SparkEngine-Linux-Release.tar.gz) - [Linux Debug (x64)](https://github.com/Krilliac/SparkEngine/releases/latest/download/SparkEngine-Linux-Debug.tar.gz) +## Where to Start + +Pick the path that matches your role: + +| Role | Recommended reading order | +|------|---------------------------| +| **New to SparkEngine** | [Getting Started](Getting-Started) → [Quick-Start Tutorial](Quick-Start-Tutorial) → [FAQ](FAQ) | +| **Programmer** | [Getting Started](Getting-Started) → [Architecture Overview](Architecture-Overview) → [Creating a Game Module](Creating-a-Game-Module) → [Entity Component System](Entity-Component-System) | +| **Artist / Designer** | [Getting Started](Getting-Started) → [Quick-Start Tutorial](Quick-Start-Tutorial) → [Editor Walkthrough](Editor-Walkthrough) → [Artist Workflow Guide](Artist-Workflow-Guide) | +| **Gameplay Designer** | [Making Your First Game](Making-Your-First-Game) → [Gameplay Systems](Gameplay-Systems) → [Scripting with AngelScript](Scripting-with-AngelScript) | +| **Multiplayer Developer** | [Multiplayer Quick Start](Multiplayer-Quick-Start) → [Networking](Networking) → [Dedicated Server](Dedicated-Server) | +| **Optimizer / QA** | [Performance Tips](Performance-Tips) → [Configuration Reference](Configuration-Reference) → [Profiler and Debugging](Profiler-and-Debugging) | + ## Wiki Navigation ### Getting Started +- [Home](Home) — You are here +- [FAQ](FAQ) — Common questions and answers - [Getting Started](Getting-Started) — Prerequisites, building, and running +- [Quick-Start Tutorial](Quick-Start-Tutorial) — Your first 10 minutes with the engine - [Architecture Overview](Architecture-Overview) — Engine design and project structure - [Creating a Game Module](Creating-a-Game-Module) — Build your first game module @@ -77,7 +93,8 @@ Pre-built binaries are published on every commit to `master`: - [Save System](Save-System) — Save/load functionality - [Day Night Cycle and Weather](Day-Night-Cycle-and-Weather) — Time-of-day and weather - [Cinematic Sequencer](Cinematic-Sequencer) — Timeline-based cinematics -- [SparkEditor](SparkEditor) — Visual editor guide +- [SparkEditor](SparkEditor) — Visual editor reference +- [Editor Walkthrough](Editor-Walkthrough) — Practical editor guide - [SparkConsole](SparkConsole) — Debug console - [Shader Pipeline](Shader-Pipeline) — Shader authoring and compilation - [Asset Pipeline](Asset-Pipeline) — Asset loading and formats @@ -93,6 +110,8 @@ Pre-built binaries are published on every commit to `master`: - [Upscaling (DLSS/FSR)](Upscaling-System) — Temporal upscaling techniques ### Advanced +- [Configuration Reference](Configuration-Reference) — All settings, console commands, and CVars +- [Performance Tips](Performance-Tips) — Optimization guide for game developers - [Build System and CMake Modules](Build-System-and-CMake-Modules) — CMake configuration and CI/CD - [Profiler and Debugging](Profiler-and-Debugging) — Frame profiling, GPU timing, and debug tools - [Testing](Testing) — Unit tests and test framework @@ -129,6 +148,6 @@ SparkEngine is licensed under the [MIT License](https://github.com/Krilliac/Spar | Editor Panels | 54 | | Test files | 238 | | Test cases | 3109+ | -| Wiki pages | 83 | -| *Last synced* | *2026-04-02 23:37* | +| Wiki pages | 88 | +| *Last synced* | *2026-04-03 00:55* | diff --git a/wiki/Performance-Tips.md b/wiki/Performance-Tips.md new file mode 100644 index 000000000..a24e43699 --- /dev/null +++ b/wiki/Performance-Tips.md @@ -0,0 +1,432 @@ +# Performance Tips + +Practical optimization guide for SparkEngine. Covers rendering, physics, audio, networking, and general best practices for shipping smooth games. + +--- + +## Measuring Performance + +Before optimizing, measure. SparkEngine provides several profiling tools: + +### In-Engine Profiling + +| Tool | How to access | What it shows | +|------|---------------|---------------| +| FPS counter | Press **F3** or `ShowFPS = true` in settings | Frame rate and frame time | +| Profiler panel | Editor → Window → Profiler | Per-system frame timing | +| Scene Statistics panel | Editor → Window → Scene Statistics | Entity/component counts, draw calls, triangles | +| Console commands | See below | On-demand metrics | + +### Useful Console Commands + +``` +render_stats # Draw calls, triangles, batches +physics_metrics # Physics step time, body count, contacts +audio_metrics # Active sources, mix time +metrics # All-in-one system overview +game_stats # Game module performance +``` + +### GPU Timing + +Enable GPU timing queries to identify GPU bottlenecks: + +```ini +[Rendering] +EnableGPUTiming = true +``` + +--- + +## Rendering Optimization + +### Use Quality Presets + +Quality presets adjust multiple settings at once: + +``` +render_quality low # Mobile/low-end +render_quality medium # Integrated graphics +render_quality high # Discrete GPU (default) +render_quality ultra # High-end GPU +``` + +### Draw Call Budget + +Keep draw calls under control. The default budget is 1000 per frame: + +```ini +[Rendering] +MaxDrawCalls = 1000 +``` + +**Reduce draw calls by:** +- Using material atlases (fewer unique materials = fewer draw calls) +- Enabling frustum culling (on by default) +- Enabling occlusion culling for dense scenes: `OcclusionCulling = true` +- Using LOD (Level of Detail) for distant objects +- Batching small objects into single meshes + +### Shadow Optimization + +Shadows are often the most expensive effect. Tune them: + +```ini +[Graphics] +ShadowQuality = 1 # 0=Off, 1=Low, 2=Medium, 3=High + +[Rendering] +ShadowMapSize = 1024 # Lower = faster (default 2048) +CascadeCount = 2 # Fewer cascades = faster (default 3) +``` + +Or disable shadows entirely for a large performance win: + +``` +shadows off +``` + +### Post-Processing Budget + +Each post-processing effect adds a full-screen pass. Disable effects you don't need: + +```ini +[PostProcess] +BloomEnabled = true # Keep — relatively cheap +[SSAO] +Enabled = false # Expensive — disable if needed +[SSR] +Enabled = false # Expensive — disable if needed +[Volumetric] +Enabled = false # Expensive — disable if needed +[MotionBlur] +Enabled = false # Moderate cost +``` + +**Cost ranking** (approximate, GPU-dependent): + +| Effect | Cost | Notes | +|--------|------|-------| +| FXAA | Very low | Cheap AA | +| Bloom | Low | 6 blur passes | +| TAA | Low–Medium | Good quality/perf ratio | +| MSAA 4x | Medium | Memory + bandwidth | +| Motion Blur | Medium | Depends on sample count | +| SSAO | Medium–High | 16 samples per pixel default | +| SSR | High | Ray-marching per pixel | +| Volumetric Fog | High | 3D ray-marching | + +### Render Scale + +Scale internal resolution for a quick FPS boost without changing window size: + +```ini +[Graphics] +RenderScale = 0.75 # 75% internal resolution +``` + +### Dynamic Quality Scaling + +Let the engine auto-adjust quality to maintain a target framerate: + +```ini +[DynamicQuality] +Enabled = true +TargetFrameTimeMs = 16.67 # 60 FPS target +MinRenderScale = 0.5 # Won't go below 50% resolution +``` + +The scaler adjusts render scale, shadow resolution, LOD bias, and texture mip bias automatically using a PID controller. + +### Texture Memory + +Control texture memory usage: + +``` +tex_quality medium # Reduce texture resolution +tex_memory 512 # Set 512 MB texture budget +``` + +```ini +[Rendering] +MaxTextureSize = 1024 # Cap texture dimensions +AnisotropyLevel = 4 # Lower anisotropy (default 16) +``` + +### Render Path Selection + +Choose the right rendering path for your scene: + +| Path | Best for | Setting | +|------|----------|---------| +| Forward | Simple scenes, few lights | `RenderPath = 0` | +| Deferred | Many lights, complex materials | `RenderPath = 1` (default) | +| Forward+ | Many lights, transparent objects | `RenderPath = 2` | +| Clustered | Very many lights (100+) | `RenderPath = 3` | + +--- + +## Physics Optimization + +### Timestep Tuning + +The default physics timestep is 60 Hz (16.67ms). For simpler games, 30 Hz saves CPU: + +```ini +[Physics] +FixedTimestep = 0.03333 # 30 Hz physics +MaxSubSteps = 2 # Fewer sub-steps +``` + +### Body Count + +Monitor your physics body count: + +``` +physics_metrics # Shows active/sleeping body counts +physics_list # List all bodies +``` + +**Tips:** +- Remove far-away dynamic bodies or put them to sleep +- Use static bodies for immovable geometry (cheaper than kinematic) +- Use simple collision shapes (box, sphere, capsule) instead of mesh colliders where possible +- Jolt supports multithreaded physics — this is on by default via the Job System + +### Debug Draw Performance + +Physics debug draw is expensive. Only enable it during development: + +``` +physics_debug off # Always disable for profiling +``` + +--- + +## Audio Optimization + +### Source Limits + +Limit concurrent audio sources: + +```ini +[AudioExtended] +MaxSources = 16 # Default 32; reduce for low-end +``` + +### 3D Audio + +If your game doesn't need spatial audio, disable it: + +```ini +[AudioExtended] +Enable3D = false # Skip 3D spatialization +``` + +### Reverb and DSP + +DSP effects add CPU cost: + +```ini +[AudioExtended] +EnableReverb = false # Disable reverb processing +EnableEAX = false # Disable EAX effects +``` + +--- + +## AI Optimization + +### Reduce AI Complexity + +Tune AI settings for your game's needs: + +```ini +[AI] +DetectionRange = 20.0 # Shorter detection = fewer checks +ReactionTime = 0.5 # Slower reactions = fewer updates +CoverSearchRadius = 10.0 # Smaller search radius +``` + +### AI Update Frequency + +Not all AI agents need to think every frame. The AI system uses behavior trees — complex trees with many conditions are more expensive. Keep trees shallow and use simple condition checks. + +--- + +## Networking Optimization + +### Replication Rate + +Lower the replication rate for games that don't need fast updates: + +```ini +[Network] +ReplicationRate = 10.0 # 10 Hz instead of default 20 Hz +``` + +### Packet Compression + +Enable compression for bandwidth-limited scenarios: + +```ini +[Network] +EnableCompression = true +``` + +### Buffer Sizes + +Adjust send/receive buffers based on your game's needs: + +```ini +[Network] +SendBufferSize = 32768 # Default 65536 +ReceiveBufferSize = 32768 +``` + +--- + +## Scripting Optimization + +### Script Limits + +Prevent runaway scripts from stalling the engine: + +```ini +[Scripting] +ExecutionTimeoutMs = 50.0 # Kill scripts after 50ms (default 100) +MaxCallStackDepth = 32 # Limit recursion (default 64) +MaxScriptMemoryMB = 32 # Limit script memory (default 64) +``` + +### Hot-Reload in Production + +Disable hot-reload in shipping builds to save file-watch overhead: + +```ini +[Scripting] +HotReloadEnabled = false +``` + +--- + +## Animation Optimization + +### Compression + +Enable animation compression to reduce memory: + +```ini +[Animation] +CompressionQuality = 3 # 0=None, 1=Low, 2=Medium, 3=High +``` + +### LOD-Based Animation + +Reduce animation quality at distance: + +```ini +[Animation] +LodDistanceMultiplier = 0.5 # More aggressive LOD transitions +``` + +### Montage Limits + +Cap concurrent animation montages: + +```ini +[Animation] +MaxActiveMontages = 2 # Default 4 +``` + +--- + +## Memory Tips + +### Texture Budgets + +Textures are typically the largest memory consumer. Guidelines: + +| Texture Type | Recommended Size | Notes | +|-------------|-----------------|-------| +| Character diffuse | 2048×2048 | Main characters | +| Environment | 1024×1024 | Tiling textures | +| Props | 512×512 | Small objects | +| UI | 256×256 or atlas | UI elements | +| Normal maps | Same as diffuse | BC5 compressed | + +### Asset Streaming + +For large worlds, the streaming system loads/unloads areas automatically. Monitor it via the **Streaming** editor panel or console. + +--- + +## Build Configuration Tips + +### Release Builds + +Always profile with Release builds. Debug builds are 5–10x slower: + +```bash +cmake --build build --config Release +``` + +### Disable Unused Features + +Disable subsystems you don't use to reduce overhead: + +```bash +cmake -B build \ + -DENABLE_AI=OFF \ # If your game has no AI + -DENABLE_NETWORKING=OFF \ # If single-player only + -DENABLE_PROFILING=OFF # For shipping builds +``` + +### Headless/Dedicated Server + +For dedicated servers, disable all rendering: + +```bash +./SparkEngine -headless -game MyGame.dll +``` + +This skips graphics initialization entirely and uses NullRHIDevice. + +--- + +## Quick Optimization Checklist + +1. **Measure first** — Use `render_stats`, `physics_metrics`, `metrics` +2. **Use quality presets** — `render_quality medium` for quick wins +3. **Check draw calls** — Keep under 1000; enable frustum/occlusion culling +4. **Tune shadows** — Often the single biggest performance lever +5. **Disable unused post-processing** — SSAO, SSR, volumetrics +6. **Use dynamic quality scaling** — Let the engine adapt automatically +7. **Monitor physics body count** — Use simple shapes, remove distant bodies +8. **Limit audio sources** — 16–32 concurrent sources is plenty +9. **Profile with Release builds** — Debug builds are not representative +10. **Test on target hardware** — Use `-test-frames 1000` for benchmarking + +--- + +## Benchmarking + +Run a reproducible benchmark: + +```bash +# Run 1000 frames and exit +./SparkEngine -test-frames 1000 -window-size 1920x1080 -game MyGame.dll +``` + +Check frame timing in the output log. Compare across changes to catch regressions. + +--- + +## See Also + +- [Configuration Reference](Configuration-Reference) — All settings and commands +- [Profiler and Debugging](Profiler-and-Debugging) — Detailed profiling guide +- [Performance Profiling Guide](Performance-Profiling-Guide) — Frame profiling workflows +- [Rendering and Graphics](Rendering-and-Graphics) — Graphics pipeline details +- [Dynamic Quality Scaler](Rendering-and-Graphics#dynamic-quality) — Auto quality adjustment +- [Troubleshooting](Troubleshooting) — Performance-related issues diff --git a/wiki/Quick-Start-Tutorial.md b/wiki/Quick-Start-Tutorial.md new file mode 100644 index 000000000..3c9ae79f4 --- /dev/null +++ b/wiki/Quick-Start-Tutorial.md @@ -0,0 +1,223 @@ +# Quick-Start Tutorial + +A hands-on guide to your first 10 minutes with SparkEngine. By the end, you will have built the engine, launched it, explored the editor, and spawned objects in a scene. + +> **Prerequisites:** You have already completed the [Getting Started](Getting-Started) guide and have a successful build. + +--- + +## Step 1: Launch the Engine + +```bash +# Windows +cd build\bin +SparkEngine.exe + +# Linux +cd build/bin +./SparkEngine +``` + +You should see a window with a 3D viewport and the debug console. The default game module (SparkGameFPS) loads automatically. + +**Default controls:** + +| Key | Action | +|-----|--------| +| W/A/S/D | Move | +| Mouse | Look around | +| Space | Jump | +| Shift | Sprint | +| Left Click | Fire (captures mouse) | +| Esc | Release mouse | +| ` (Backtick) | Toggle console | +| F1 | Toggle editor | +| F3 | Toggle FPS stats | + +--- + +## Step 2: Open the Console + +Press **`** (backtick) to open the debug console. Try these commands: + +``` +help # List all available commands +version # Show engine version +render_stats # Display rendering statistics +physics_metrics # Show physics performance +``` + +The console supports tab-completion and command history (up/down arrows). + +--- + +## Step 3: Explore the Editor + +Press **F1** to open the editor overlay. You will see these panels: + +| Panel | Purpose | +|-------|---------| +| **Scene View** (center) | 3D viewport — click and drag to orbit, scroll to zoom | +| **Hierarchy** (left) | Lists every entity in the scene | +| **Inspector** (right) | Shows components of the selected entity | +| **Asset Browser** (bottom) | Browse project files | +| **Console** (bottom) | Log output and commands | + +### Try it: + +1. **Select an entity** — Click any item in the Hierarchy panel +2. **Inspect it** — The Inspector shows its Transform, MeshRenderer, and other components +3. **Move it** — In the Scene View, use the gizmo handles (arrows) to drag the entity. Press **W** for translate, **E** for rotate, **R** for scale gizmos +4. **Add a component** — In the Inspector, click "Add Component" and choose a type + +--- + +## Step 4: Spawn Objects via Console + +Use the console to spawn entities at specific coordinates: + +``` +spawn box 0 5 0 # Spawn a physics box 5 units above origin +spawn sphere 2 10 0 # Spawn a physics sphere +spawn box -3 8 0 # Another box +``` + +Watch the physics objects fall and collide. Toggle physics debug visualization: + +``` +physics_debug on # Show collision shapes and contacts +physics_debug off # Hide debug overlay +``` + +--- + +## Step 5: Adjust the World + +Try changing the environment: + +``` +# Time of day +time_set 6 # Sunrise +time_set 12 # Noon +time_set 18 # Sunset +time_set 0 # Midnight +time_speed 10 # Speed up the day/night cycle + +# Weather +weather clear +weather rain +weather snow +weather storm + +# Physics +physics_gravity 0 -5 0 # Low gravity +physics_gravity 0 -20 0 # Normal gravity (default) +``` + +--- + +## Step 6: Change Graphics Settings + +Experiment with rendering settings: + +``` +# Quality presets +render_quality low +render_quality high +render_quality ultra + +# Individual toggles +wireframe on # Wireframe rendering +wireframe off +vsync off # Disable VSync +shadows off # Disable shadows +hdr on # Enable HDR +``` + +Or edit `Resources/Config/settings.ini` for persistent changes. See [Configuration Reference](Configuration-Reference) for all available settings. + +--- + +## Step 7: Try Game Modes (FPS Module) + +If the FPS game module is loaded: + +``` +# Cheat commands +god # Toggle god mode +noclip # Toggle noclip (fly through walls) +player_tp 0 50 0 # Teleport to coordinates + +# Game modes +gamemode freeplay # Free exploration +gamemode deathmatch # Deathmatch mode +gamemode survival # Wave-based survival + +# Inventory +give 1 # Give item ID 1 +inventory # Show inventory +``` + +Start a wave-based survival round: + +``` +wave_start # Begin waves +wave_status # Check current wave +wave_difficulty 2.0 # Increase difficulty +``` + +--- + +## Step 8: Look Under the Hood + +Check what the engine is doing: + +``` +engine_subsystems # List all active subsystems +metrics # Comprehensive system metrics +asset_list # All loaded assets +shader_list # All loaded shaders +``` + +Toggle debug visualizations: + +``` +physics_debug on # Collision shapes +``` + +Open the **Profiler** panel in the editor (Window menu) to see frame timings, draw call counts, and system performance. + +--- + +## What's Next? + +Now that you have a feel for the engine, explore these guides based on your role: + +### Programmers +1. [Creating a Game Module](Creating-a-Game-Module) — Build your own game module +2. [Entity Component System](Entity-Component-System) — ECS architecture +3. [Scripting with AngelScript](Scripting-with-AngelScript) — Hot-reload scripting + +### Artists & Designers +1. [Artist Workflow Guide](Artist-Workflow-Guide) — Asset creation and import +2. [Editor Walkthrough](Editor-Walkthrough) — Complete editor guide +3. [Terrain and Procedural Generation](Terrain-and-Procedural-Generation) — Terrain tools + +### Gameplay Designers +1. [Making Your First Game](Making-Your-First-Game) — Build a complete game +2. [Gameplay Systems](Gameplay-Systems) — Weapons, inventory, quests +3. [AI and Navigation](AI-and-Navigation) — Behavior trees and pathfinding + +### Multiplayer Developers +1. [Multiplayer Quick Start](Multiplayer-Quick-Start) — Set up client/server +2. [Networking](Networking) — Full networking reference +3. [Dedicated Server](Dedicated-Server) — Headless server setup + +--- + +## See Also + +- [FAQ](FAQ) — Common questions and answers +- [Configuration Reference](Configuration-Reference) — All settings and commands +- [Editor Walkthrough](Editor-Walkthrough) — Practical editor guide +- [Troubleshooting](Troubleshooting) — Common issues and solutions diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md index 24d939047..de2d196b3 100644 --- a/wiki/_Sidebar.md +++ b/wiki/_Sidebar.md @@ -2,9 +2,12 @@ ### Getting Started - [Home](Home) +- [FAQ](FAQ) - [Getting Started](Getting-Started) +- [Quick-Start Tutorial](Quick-Start-Tutorial) - [Making Your First Game](Making-Your-First-Game) - [Artist Workflow Guide](Artist-Workflow-Guide) +- [Editor Walkthrough](Editor-Walkthrough) - [Architecture Overview](Architecture-Overview) - [Engine Architecture Flowchart](Engine-Architecture-Flowchart) - [Creating a Game Module](Creating-a-Game-Module) @@ -78,6 +81,8 @@ - [Mesh Shaders](Mesh-Shaders) ### Advanced +- [Configuration Reference](Configuration-Reference) +- [Performance Tips](Performance-Tips) - [Threading Model](Threading-Model) - [Memory Management Patterns](Memory-Management-Patterns) - [Build System and CMake Modules](Build-System-and-CMake-Modules)