PIRL -- Perceptual Illusion Rendering + Lighting

Perception-driven rendering optimization framework for Godot 4.x, built by Inner Void Studio.

Full architecture: addons/pirl/docs/PIRLSpec.md

Status

Block 6 -- Tools + Testing, done. All 6 blocks of the original plan are complete. demo/pirl_demo.tscn exercises every system: room geometry on pirl_surface, a fullscreen pirl_post overlay, 2 lights of different types for the importance system, staggered-distance physics props for PIRLPhysicsOptimizer and PIRLLODManager, and a live FPS/quality HUD (demo/pirl_benchmark_hud.gd, press B for a timed avg/min/max sample).

Honest note on how this was built: there's no way to open or run the actual Godot editor from here, so the demo is a scene built from a script (easier to verify carefully) rather than a hand-typed .tscn node tree (much easier to get subtly wrong with no way to catch it). Every PIRL.* call in it was cross-checked against pirl_renderer.gd's real method list before this was packaged -- but it has never actually run. The first real test is on your machine.

Try the demo

1. Open this whole PIRL/ folder as a Godot project (or copy demo/ into an existing project alongside an already-installed addons/pirl/).
2. Make sure the PIRL plugin is enabled (Project Settings -> Plugins).
3. Open and run demo/pirl_demo.tscn.
4. WASD + mouse to move, Esc to release the cursor, B to start/stop a timed FPS sample (prints to the Output panel when you stop it).

Install

1. Copy addons/pirl/ into your Godot project's addons/ folder.
2. Project Settings -> Plugins -> enable PIRL.
3. A PIRL autoload singleton is now available game-wide.

What's in this drop

addons/pirl/
├── plugin.cfg              Godot plugin manifest
├── plugin.gd                Editor entry point, registers the PIRL autoload
├── core/
│   ├── pirl_renderer.gd           Wires together all six systems below
│   ├── pirl_lighting_manager.gd   Stage 2 -- picks + feeds the 2 "important" lights
│   ├── pirl_temporal_upscaler.gd  Stage 3 -- wraps Godot's built-in FSR1/FSR2/Bilinear
│   ├── pirl_foveal_pass.gd        Stage 4 -- generates the screen-space foveal mask
│   ├── pirl_budget_manager.gd     Stage 6 -- adaptive quality, GPU budget vs CPU budget
│   ├── pirl_lod_manager.gd        Wraps Godot's built-in visibility ranges
│   ├── pirl_physics_optimizer.gd  Distance-based RigidBody3D freezing
│   └── pirl_texture_streamer.gd   Distance-based texture tier swapping
├── shaders/
│   ├── pirl_surface.gdshader   Stage 1 + Stage 2 -- base render + perceptual lighting
│   ├── pirl_post.gdshader      Stage 5 -- post-processing illusion
│   └── pirl_particle.gdshader  Lightweight GPU particle effects
├── resources/
│   └── pirl_preset.gd       PIRLPreset -- the schema every preset is built from
├── presets/
│   ├── semi_realistic.tres
│   ├── stylized.tres           Default starting point -- see its description
│   ├── horror.tres
│   └── cel_shading.tres        Approximation only -- see its description for the gap
└── docs/
    └── PIRLSpec.md           Full technical specification

demo/                          Sibling to addons/ -- not part of the portable package
├── pirl_demo.tscn             Open and run this
├── pirl_demo.gd                Builds the whole test scene from code
└── pirl_benchmark_hud.gd       Live FPS/quality readout + B-key timed sample

Roadmap

Block	Contents	Status
1. Foundation	Spec, plugin skeleton, preset schema	Done
2. Core Shaders	pirl_surface / pirl_post / pirl_particle (shadows folded into pirl_surface)	Done
3. Rendering Systems	Renderer, temporal upscaler, foveal pass, lighting manager	Done
4. Optimization Systems	LOD, budget manager, physics optimizer, texture streamer	Done
5. Presets	semi_realistic / stylized / horror / cel_shading	Done
6. Tools + Testing	Demo scene, benchmarks, doc polish	Done