Skip to main content
Launch specialized debug views for testing rendering, gameplay systems, and development sandboxes.

​
Usage

crimson view <name> [OPTIONS]

​
Arguments

​
name
string
required
View name to launch.Available views are defined in crimson.views.Common views:
  • empty — Empty scene
  • lighting-debug — Lighting system debug
  • sprite-test — Sprite rendering test
  • terrain-test — Terrain rendering test

​
Options

​
--width
int
default:"1024"
Window width in pixels.
​
--height
int
default:"768"
Window height in pixels.
​
--fps
int
default:"60"
Target frame rate.
​
--dump-shader-debug-views
flag
lighting-debug only: Run autodiag and dump screenshots for each shader debug mode.
​
--dump-shader-debug-frames
int
default:"399"
lighting-debug only: Total autodiag frames when --dump-shader-debug-views is set.Must be ≥ 30.
​
--autotune-shadow-defaults
flag
lighting-debug only: Run automated quality/perf sweep and print best tuning preset.
​
--autotune-shadow-frames
int
default:"96"
lighting-debug only: Sampled frames per preset when --autotune-shadow-defaults is set.Must be ≥ 12.
​
--preserve-bugs
flag
Preserve known original exe bugs/quirks.
​
--assets-dir
Path
default:"artifacts/assets"
Assets root directory.

​
Available Views

To see all available views: 
crimson view unknown
Output: 
unknown view 'unknown'. Available: empty, lighting-debug, sprite-test, terrain-test, ...

​
Examples

​
Empty Scene

crimson view empty
Launches minimal raylib window.

​
Lighting Debug View

crimson view lighting-debug --width 1920 --height 1080

​
Dump All Shader Debug Modes

crimson view lighting-debug --dump-shader-debug-views --dump-shader-debug-frames 600
Generates screenshots for each shader debug mode.

​
Autotune Shadow Settings

crimson view lighting-debug --autotune-shadow-defaults --autotune-shadow-frames 120
Runs performance sweep and prints optimal shadow settings.

​
Sprite Test

crimson view sprite-test --fps 144

​
Custom Assets

crimson view terrain-test --assets-dir ./custom_assets

​
View Context

Views receive a ViewContext: 
class ViewContext:
    assets_dir: Path
    preserve_bugs: bool
This provides asset access and bug preservation flag.

​
Lighting Debug View

The lighting-debug view has special diagnostic modes:

​
Shader Debug Modes

Cycle through shader debug visualizations:
  • Normals
  • Depth
  • Shadows
  • Ambient occlusion
  • Light accumulation
Use --dump-shader-debug-views to export all modes.

​
Shadow Autotuning

The --autotune-shadow-defaults flag runs performance benchmarks:
  1. Tests multiple shadow quality presets
  2. Measures frame time for each
  3. Finds best quality/performance balance
  4. Prints recommended settings
Useful for optimizing shadow settings on different hardware.

​
Controls

Common view controls:
  • ESC — Close view
  • F12 — Screenshot
View-specific controls vary. Check view implementation for details.

​
Error Handling

​
Unknown View

crimson view nonexistent
Output: 
unknown view 'nonexistent'. Available: empty, lighting-debug, ...
Exit code: 1

​
Conflicting Flags

crimson view lighting-debug --dump-shader-debug-views --autotune-shadow-defaults
Output: 
--dump-shader-debug-views and --autotune-shadow-defaults cannot be used together
Exit code: 1

​
Wrong View for Flag

crimson view empty --dump-shader-debug-views
Output: 
--dump-shader-debug-views is only supported for view 'lighting-debug'
Exit code: 1

​
Use Cases

​
Renderer Development

Test rendering systems in isolation: 
crimson view lighting-debug

​
Asset Debugging

Verify sprite/texture loading: 
crimson view sprite-test --assets-dir ./test_assets

​
Performance Tuning

Benchmark render paths: 
crimson view lighting-debug --autotune-shadow-defaults --fps 120

​
Screenshot Generation

Generate reference images: 
crimson view terrain-test --dump-shader-debug-views

​
Creating Custom Views

Views are defined in crimson/views/: 
from crimson.views import ViewDefinition
from grim.view import ViewContext

def my_view_factory(ctx: ViewContext):
    # Return view instance
    return MyView(ctx)

MY_VIEW = ViewDefinition(
    name="my-view",
    title="My Custom View",
    factory=my_view_factory,
)
Register in crimson/views/__init__.py: 
from .my_view import MY_VIEW

def all_views():
    return [MY_VIEW, ...]

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us