Shared terminal effects¶
Inherit the world kit to get effects automatically. Use the custom-renderer example when replacing terminal presentation.
| Task | Section |
|---|---|
| Wire effects to a custom surface | Custom renderer |
| Capture a transition | Retained state |
| Replace the sheet shader | Shader contract |
| Configure focus and blur | Depth of field |
Use the shared world kit¶
The kit installs and rebinds TerminalEffects automatically. Set the world's
Effects Preset; use its terminal_effects property only for extra control.
Native keystrokes trigger effects. Shell output does not count as typing.
Custom world renderer¶
Add one component per visible terminal presentation. Keep it under a world-owned Node3D so removing the world removes visuals and signal connections, not shells.
const TerminalFX = preload("res://scenes/TerminalEffects.gd")
const FXConfig = preload("res://scenes/Effects.gd")
var effects: Node3D
func install_effects(terminal: Node, viewport: SubViewport) -> void:
var settings = FXConfig.new()
settings.load_config("res://presets/flat.conf") # or your plugin's preset
effects = TerminalFX.new()
add_child(effects)
effects.configure(settings)
var material = TerminalFX.create_sheet_material(viewport)
material.set_shader_parameter("wall_shade", 0.0)
$TerminalQuad.material_override = material
effects.bind_terminal(terminal, material, surface_frame, presentation_frame.bind(viewport))
func presentation_frame(point: Vector2, viewport: SubViewport) -> Variant:
# Logical terminal texture pixels, including native padding/scroll offset.
# During a transition use the displayed live pane's transform; return null
# when only frozen glyphs are visible. Do not use the eventual landing pose.
return surface_frame(point / Vector2(TerminalFX.layout_size(viewport)))
func surface_frame(uv: Vector2) -> Transform3D:
# For a centered QuadMesh facing +Z. UV origin is its top-left corner.
var quad = $TerminalQuad
var size: Vector2 = quad.mesh.size
var point := Vector3((uv.x - 0.5) * size.x, (0.5 - uv.y) * size.y, 0.0)
return Transform3D(quad.global_basis.orthonormalized(), quad.to_global(point))
Surface contract¶
| Responsibility | Rule |
|---|---|
| Material | Uses viewport texture; does not modify PTY state |
| Resize | Update tex_size |
| Coordinates | Logical pixels through layout_size(viewport); UV mapping uses +Y up, +Z toward viewer |
| Particle size | Tune scene.typing.particles_scale for world units |
| Shader replacement | Preserve ripple, splash, cursor, and time uniforms |
| Rebind | Disconnects old terminal and clears trails/splash |
Cursor cells map through the real content rect; billboard materials preserve authored scale.
Frame timing¶
- Default automatic mode advances idle/typing behavior.
- For a shared state machine, set
automatic = falseand calladvance(delta,resolved_frame)once per frame. - Update camera/transition geometry before
advance_cursor(dt)in manual mode. enabled = falsesuppresses triggers/deformation.
Camera motion belongs to the world, not the effects component.
Extra triggers and transitions¶
typed(uv) lets the world react to typing. The first key selects its particle
preset. pulse(uv) is for explicit non-key events; calling it again for a native
keystroke would double-trigger.
Transition glyph/image layers retain live ink gain, exposure, opacity, and edge brightness. See retained state and shader/lens details.