# dragon_stone
Stone material for the dragon head sculpture in the `fx_breath` scene. 39 entities under the
`dragon` parent wear it: the skull, throat, upper and lower jaw, chin, snout tip, two brows, two
cheeks, two horns, two small horns, four spine cones, twenty teeth and the plinth. They are built-in
rounded boxes and cones, and a cube for the plinth.
Shader: `castle_stone` (`castle_stone.shader`). Its README describes procedural masonry in world
space: running-bond blocks, bevelled joints, grain, pitting and soot stains climbing from the
ground. It picks its projection plane from the dominant normal axis, so walls, plinths and carved
forms read as one stone. It is an engine-lit `surface()` shader with metallic fixed at 0. The
`castle_stone` material is the other material on this shader.
Render state: the defaults (opaque blend, back faces culled, depth write on); mat.yaml sets only the
shader and its values.
## Properties
- `tint: [0.62, 0.66, 0.6, 1.0]`: multiplied into the stone albedo; it darkens the stone and shifts
it slightly toward green.
- `block_size: [2.4, 1.2]`: block width and row height in world units (default [1.3, 0.62]); the
shader varies each row's block width between 0.85 and 1.35 times the first value.
- `roughness: 0.8`: perceptual roughness (default 0.92).
- `soot_height: 1.0`: world height where the soot stain fades out (default 3.5); the soot is
strongest at y = 0.
# castle_stone
Masonry material for the courtyard walls in the `fx_breath` scene. 35 entities under the `walls`
parent wear it, all built-in cubes: the four walls (`wall_left`, `wall_right`, `wall_back`,
`wall_far`), ten pillars (`pillar_l*`, `pillar_r*`) and 21 merlons. The `dragon_stone` material is a
second material on the same shader.
Shader: `castle_stone` (`castle_stone.shader`). Its README describes procedural masonry in world
space: running-bond blocks, bevelled joints, grain, pitting and soot stains climbing from the
ground. It picks its projection plane from the dominant normal axis, so walls, plinths and carved
forms read as one stone. It is an engine-lit `surface()` shader with metallic fixed at 0.
Render state: the defaults (opaque blend, back faces culled, depth write on); mat.yaml sets only the
shader and its values.
## Properties
- `tint: [1.0, 1.0, 1.0, 1.0]`: colour multiplied into the stone albedo; white keeps the shader's
own stone colours.
- The other properties take the shader defaults: `block_size` [1.3, 0.62] (block width and row
height in world units), `roughness` 0.92 (perceptual roughness) and `soot_height` 3.5 (the world
height where the soot stain fades out; it is strongest at y = 0).
# dragon_eye
Glowing eye material for the stone dragon head in the `fx_breath` scene. The two eye entities
(`eye_1` and `eye_-1`, built-in spheres under the `dragon` parent) wear it.
Shader: the built-in `pbr` shader (`@builtin::shaders.pbr`), the engine's standard physically based
material: the glTF metallic-roughness workflow lit by the shared `pbr_shading` model. Its glow
output is `emissive` times `emissive_intensity` (default 1.0) times the emissive texture (default
white).
Render state: the defaults (opaque blend, back faces culled, depth write on); mat.yaml sets only the
shader and its values.
## Properties
- `base_color: [0.05, 0.01, 0.0, 1.0]`: albedo, a very dark red-brown.
- `emissive: [9.0, 1.6, 0.12, 1.0]`: emissive colour; with `emissive_intensity` at 1.0 the eyes emit
this orange at values above 1.
- `roughness: 0.3`: perceptual roughness.
- Every other `pbr` property keeps its default, including `metallic` 0.0.
# courtyard_flagstone
Ground material for the dragon courtyard in the `fx_breath` scene. The scene's `ground` entity (a
built-in cube scaled 50 x 0.2 x 50 at (170, -0.1, 150)) wears it, and the `DragonBreathDirector`
component on the `dragon_breath` entity holds it in its `material` field.
Shader: `flagstone_scorch` (`flagstone_scorch.shader`). Its README describes running-bond flagstone
paving that scorches where a periodic fire-breath sweep has passed. The sweep is analytic (`axis =
amp * sin(2*pi*t/period)` seen from `mouth`), so each stone works out when the flame last crossed it
and how hot and sooty it is now: glowing orange in the joints and veins first, cooling through dull
red to black soot. Heat drives the emissive output through a black, deep red, orange and
yellow-white ramp; soot darkens the albedo and raises roughness.
`DragonBreathDirector` writes `sync_time` every frame as the breath generator's clock modulo its
`period`, so the scorch follows the same sweep as the flame of `proc/dragon_breath.procGraph`. In
the scene the director uses mouth (170, 2.4, 141), amplitude 0.72 and period 14, the same values
this material sets.
Render state: the defaults (opaque blend, back faces culled, depth write on); mat.yaml sets only the
shader and its values.
## Properties
- `mouth: [170, 141]`: world x and z of the dragon's mouth, the point the sweep and the reach are
measured from.
- `sweep_amp: 0.72`: half-width of the sweep in radians; the flame axis swings between -0.72 and
0.72, measured from +z toward +x.
- `sweep_period: 14.0`: seconds for one full left-right-left sweep.
- `heat_tau: 5.0`: cooling time constant in seconds (default 2.6). Each slab cools with between 0.75
and 1.45 times this value, and the mortar around it with 1.9 times the slab's.
- `soot_tau: 22.0`: time constant in seconds for the soot of the last crossing (default 9.0). Inside
the flame's reach the soot term is `0.55 + 0.45 * exp(-seconds since the crossing / soot_tau)`,
varied by grain.
- `flame_width: 0.2`: angular width of the flame front in radians (default 0.13); the shader widens
it with distance as `flame_width * (0.7 + 0.05 * r)`.
- `reach_near: 3.0` and `reach_far: 19.0`: the radial band, in metres from the mouth, that the flame
scorches; both edges are roughened by noise that moves with time.
- Set at runtime or left at the default: `sync_time` (written by `DragonBreathDirector`) and `glow`
1.0 (multiplier on the emissive heat colour).
# dragon_breath
A dragon's fire breath sweeping a courtyard: a jet of flame from the mouth, rolling dark smoke born
where the flames die, and embers that drift and settle. The sweep is a function of time alone
(yaw = 0.72 sin(2 pi t / 14), from world +Z toward +X), so the effect loops forever, and the
Procgen Effects Showcase world's courtyard shader `flagstone_scorch` evaluates the same sweep to scorch the stones where the jet
has just passed. The mouth stands at (0, 2.4, -9) in the generator's own space.
```lua
-- `graph` is this graph's reference: the AssetRef `asset.resolve` or a search returns for it.
local e = entity.spawn("dragon_breath", { position = { 0, 0, 0 } })
e.component.add("Generator", { graph = graph, playOn = "load", ending = "loop" })
```
| Output | What it draws |
|---|---|
| `flame` | The flame jet, additive, `dragon_flame` shader |
| `smoke` | The smoke the flames leave, `dragon_smoke` shader |
| `embers` | Embers drifting down, additive, `dragon_ember` shader |
In the Procgen Effects Showcase world's `fx_breath` scene, the `DragonBreathDirector` component on the same entity keeps
the ground's scorch and a set of flickering lights in step with this graph's clock. The timeline
has no end and plays at 60 fps.
# DragonBreathDirector
DragonBreathDirector sits on the entity that runs the dragon-breath Generator and keeps three things in
step with that generator's clock: the `sync_time` property of a material, a set of flickering point
lights that ride along the fire jet, and playback of the generator itself. The fire, the light it
throws and the scorch it leaves on the ground all read the same clock, so they agree.
The fx_breath scene uses it on the `dragon_breath` entity, next to that entity's Generator, with
`material` set to `courtyard_flagstone` (a material on the `flagstone_scorch` shader), `mouth` at
`{ x = 170, y = 2.4, z = 141 }` and `frameCamera` off. The jet sweeps as
`yaw(t) = amplitude * sin(2 * pi * t / period)`, measured from world +Z toward +X; the source states
that these sweep constants must match `proc/dragon_breath.procGraph` and `flagstone_scorch.shader`.
It needs a Generator component on its own entity. It runs at `executionOrder = 50`.
## Fields
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `material` | assetRef (material) | nil | Material whose sync_time follows the breath's clock. |
| `mouth` | vec3 | `{ x = 0, y = 2.4, z = -9 }` | World position of the dragon's mouth, metres. |
| `amplitude` | number | 0.72 | Half-width of the sweep, radians. |
| `period` | number | 14.0 | Seconds for one full left-right-left sweep. |
| `lightCount` | number | 4 | Firelight point lights riding the jet. |
| `frameCamera` | bool | true | Open the player's orbit camera on the wide hero shot. |
| `cameraDistance` | number | 18 | Orbit distance of the opening shot, metres behind the avatar. |
| `cameraHeight` | number | 6 | Height of the opening shot above the avatar's feet, metres. |
| `cameraAim` | number | 2 | Height above the avatar's feet the opening shot looks at, metres. |
All fields are `NoSync`.
## Lifecycle
- `awake()`: binds the Generator on its entity and the `material` asset, then builds the lights. It
despawns every entity matching `dragon_firelight_*` and spawns `lightCount` temporary entities named
`dragon_firelight_1`, `dragon_firelight_2` and so on, each with a point `Light` (colour
`{ 1.0, 0.42, 0.1 }`, intensity 0, range 14, shadows off).
- `start()`: calls `play()` on the Generator.
- `update(dt)`: runs the per-frame drive described below.
- `editorUpdate(dt)`: runs the same drive while `engine.paused` is true.
- `onDestroy()`: despawns the lights it spawned.
Each drive step:
1. When `frameCamera` is on, every 0.5 seconds it looks for entities named `CameraRig` that carry a
`controller.orbital_follow` component and, once per rig, sets `maxRadiusScale = 6`,
`ringCenter = { height = cameraHeight, radius = 4.5 }`, `radiusScale = cameraDistance / 4.5` and
`aimHeight = cameraAim`. Each rig is framed once, so the player's own scroll and orbit stay in the
player's hands afterwards.
2. It rebinds the Generator if it has none yet, and rebuilds the lights if the first one is gone.
3. It reads the generator's time `t` with `getTime()` and sets the material's `sync_time` to
`t % period`, the phase of the periodic sweep.
4. It computes the sweep yaw and places light `i` of `n` along the jet, at `1.5 + 13 * (i / n)` from
the mouth and `1.5 * (i / n)` below it (held at a height of at least 0.9). Each light's intensity is
`(60 - 34 * (i / n))` scaled by its own sum-of-sines flicker, and its radius is `12 + 10 * (i / n)`.
# effectShowcase
The procedural effects of the Procgen Effects Showcase world. Each one is a `.procGraph` that plays
through a `Generator`, and every shader, material and module a graph draws with sits beside it in
this package, so the package carries everything its graphs need. Each graph's README says what it
makes, how to place it and what each of its inputs changes.
## Contents
| Folder | Graphs | What they make |
|---|---|---|
| `combat/` | `impact`, `muzzleFlash`, `tracer` | A round striking a hard surface, the bloom at a barrel as a weapon fires, and the glowing streak of a round in flight. They draw with `fxFlash`, `fxSmoke` and `fxSpark` in `combat/shaders/`. |
| `blast/` | `wall_blast` | A charge blowing a breach through a stone block wall, on a 9.6 s loop. |
| `storm/` | `storm`, `tower` | A thunderstorm around a lone tower: wind-driven rain, lightning striking on the schedule `schedule.module` keeps, and sparks and smoke where strikes land. `tower` is the stone keep it stands around. |
| `rift/` | `arcane_rift` | A rift tearing open in the ground, its motes and rubble moved by the compute shaders in `rift/compute/`. |
| `dragon/` | `dragon_breath` | A dragon's fire breath sweeping a courtyard: a flame jet, rolling smoke and drifting embers. |
| `launch/` | `launch` | A heavy-lift rocket liftoff on one looping timeline, with the heat-haze material `rk_haze_mat`. |
| `waterfall/` | `wf_env`, `wf_water`, `wf_spray`, `wf_foam`, `wf_mist` | A waterfall built in parts: the cliff, basin and boulders, the falling and still water, the droplets, the foam where the falls land, and the mist with its rainbow. Its water materials are in `waterfall/materials/`. |
| `shaders/` | | `fx_noise`, the noise functions the waterfall and wall blast shaders include. |
## Playing one
A graph plays on a `Generator` component bound to it:
```lua
-- `graph` is the graph's reference: the AssetRef `asset.resolve` or a search returns for it.
local e = entity.spawn("impact", { position = { 0, 1, 0 } })
e.component.add("Generator", { graph = graph, playOn = "load" })
```
Set a graph's inputs with the Generator's `params`, e.g. `params = { size = 3 }`.