feat(vfx): Phase C.1 — PES particle renderer + post-review fixes
Ports retail's ParticleEmitterInfo / Particle::Init / Particle::Update
(0x005170d0..0x0051d400) and PhysicsScript runtime to a C# data-layer
plus a Silk.NET billboard renderer. Sky-PES path is debug-only behind
ACDREAM_ENABLE_SKY_PES because named-retail decomp confirms GameSky
copies SkyObject.pes_id but never reads it (CreateDeletePhysicsObjects
0x005073c0, MakeObject 0x00506ee0, UseTime 0x005075b0).
Post-review fixes folded into this commit:
H1: AttachLocal (is_parent_local=1) follows live parent each frame.
ParticleSystem.UpdateEmitterAnchor + ParticleHookSink.UpdateEntityAnchor
let the owning subsystem refresh AnchorPos every tick — matches
ParticleEmitter::UpdateParticles 0x0051d2d4 which re-reads the live
parent frame when is_parent_local != 0. Drops the renderer-side
cameraOffset hack that only worked when the parent was the camera.
H3: Strip the long stale comment in GfxObjMesh.cs that contradicted the
retail-faithful (1 - translucency) opacity formula. The code was
right; the comment was a leftover from an earlier hypothesis and
would have invited a wrong "fix".
M1: SkyRenderer tracks textures whose wrap mode it set to ClampToEdge
and restores them to Repeat at end-of-pass, so non-sky renderers
that share the GL handle can't silently inherit clamped wrap state.
M2: Post-scene Z-offset (-120m) only fires when the SkyObject is
weather-flagged AND bit 0x08 is clear, matching retail
GameSky::UpdatePosition 0x00506dd0. The old code applied it to
every post-scene object — a no-op today (every Dereth post-scene
entry happens to be weather-flagged) but a future post-scene-only
sun rim would have been pushed below the camera.
M4: ParticleSystem.EmitterDied event lets ParticleHookSink prune dead
handles from the per-entity tracking dictionaries, fixing a slow
leak where naturally-expired emitters' handles stayed in the
ConcurrentBag forever during long sessions.
M5: SkyPesEntityId moves the post-scene flag bit to 0x08000000 so it
can't ever overlap the object-index range. Synthetic IDs stay in
the reserved 0xFxxxxxxx space.
New tests (ParticleSystemTests + ParticleHookSinkTests):
- UpdateEmitterAnchor_AttachLocal_ParticlePositionFollowsLiveAnchor
- UpdateEmitterAnchor_AttachLocalCleared_ParticleFrozenAtSpawnOrigin
- EmitterDied_FiresOncePerHandle_AfterAllParticlesExpire
- Birthrate_PerSec_EmitsOnePerTickWhenIntervalElapsed (retail-faithful
single-emit-per-frame behavior)
- UpdateEntityAnchor_WithAttachLocal_MovesParticleToLiveAnchor
- EmitterDied_PrunesPerEntityHandleTracking
dotnet build green, dotnet test green: 695 / 393 / 243 = 1331 passed
(up from 1325).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik
parent
1f82b7604e
commit
ec1bbb4f43
28 changed files with 2444 additions and 780 deletions
|
|
@ -178,24 +178,25 @@ missing is the plugin-API surface.
|
|||
---
|
||||
|
||||
|
||||
## #2 — Lightning visual not wired (dat-baked PES triggers)
|
||||
## #2 — Lightning visual mismatch (sky PES path disproved)
|
||||
|
||||
**Status:** OPEN
|
||||
**Severity:** MEDIUM
|
||||
**Filed:** 2026-04-25
|
||||
**Component:** weather / sky / vfx
|
||||
|
||||
**Description:** Retail's Rainy DayGroup in the Dereth Region dat contains 12+ `SkyObject` entries with non-zero `PesObjectId` and narrow visibility windows (5–70 ms at keyframe-boundary moments) that drive PhysicsScript-authored flash + thunder effects. We render the sky meshes but ignore the PES path, so no lightning flashes appear during storms. The fragment-shader flash bump on `uFogParams.z` is already wired in `sky.frag` — only the CPU-side PES→runner wire is missing.
|
||||
**Description:** Lightning/storm sky visuals still do not match retail. A 2026-04-28 named-retail recheck disproved the prior assumption that `SkyObject.PesObjectId` drives sky-render flash particles: `SkyDesc::GetSky` copies the field into `CelestialPosition.pes_id`, but `GameSky::CreateDeletePhysicsObjects`, `GameSky::MakeObject`, and `GameSky::UseTime` never read it.
|
||||
|
||||
**Root cause / status:** Research complete. Implementation is: in `SkyRenderer.Render`, detect visibility-window entry on any SkyObject with `obj.PesObjectId != 0`, call `PhysicsScriptRunner.Play(pesObjectId, ownerId: sky-owner, anchorPos: camera)`, and route any `SetFlash` / `Sound` hooks from the script into `uFogParams.z` + audio.
|
||||
**Root cause / status:** Open again. The sky-PES path is non-retail and must stay disabled for normal rendering. The remaining mismatch likely lives in the sky/weather mesh material path, the lightning/fog flash path, or another weather subsystem outside `GameSky`; do not reintroduce per-SkyObject PES playback without new decompile evidence.
|
||||
|
||||
**Files:**
|
||||
- `src/AcDream.App/Rendering/Sky/SkyRenderer.cs` — add per-SkyObject PES dispatch inside the visibility loop
|
||||
- `src/AcDream.Core/Vfx/PhysicsScriptRunner.cs` — already shipped (Phase 6a); exposes `Play(scriptId, entityId, anchorWorldPos)`
|
||||
- `src/AcDream.Core/Lighting/SceneLightingUbo.cs` — `FogParams.Z` is the flash slot; needs a sink that bumps it and decays
|
||||
- `src/AcDream.App/Rendering/Shaders/sky.frag` — flash bump already wired (`rgb += flash * vec3(1.5, 1.5, 1.8)`)
|
||||
- `src/AcDream.App/Rendering/Sky/SkyRenderer.cs` — sky/weather mesh draw, material state, pre/post split
|
||||
- `src/AcDream.App/Rendering/Shaders/sky.frag` — flash/fog/lightning coloration path
|
||||
- `src/AcDream.Core/World/SkyDescLoader.cs` — keep `PesObjectId` parsed for diagnostics, not render playback
|
||||
|
||||
**Research:**
|
||||
- `docs/research/2026-04-28-pes-pseudocode.md` — C.1 correction: `CelestialPosition.pes_id` copied but ignored by GameSky
|
||||
- `docs/research/2026-04-23-sky-pes-wiring.md` — earlier decompile trace reached the same no-sky-PES conclusion
|
||||
- `docs/research/2026-04-23-lightning-real.md` (decompile trace + dat discovery)
|
||||
- `docs/research/2026-04-23-physicsscript.md` (runtime semantics)
|
||||
- `docs/research/2026-04-23-lightning-crossfade.md` (crossfade mechanism)
|
||||
|
|
@ -281,7 +282,9 @@ missing is the plugin-API surface.
|
|||
|
||||
**Description:** Retail renders a dynamic colored "light play" effect in the sky during certain Rainy/Cloudy DayGroup time windows. The user describes it as aurora-borealis-style. acdream renders no comparable effect.
|
||||
|
||||
**Root cause:** PES (Particle Effect Schedule) particles attached to SkyObjects via the `CelestialPosition.pes_id` field. Retail header at `acclient.h` line 35451 (verbatim):
|
||||
**Root cause / status:** Open again. The prior root cause was wrong: `CelestialPosition.pes_id` exists in the retail header and is populated by `SkyDesc::GetSky`, but named retail `GameSky` code does not read it during sky object creation, update, or draw. A 2026-04-28 C.1 experiment that played those PES ids produced colored blobs/wash that did not match retail's broad aurora-like rays, and the path is now debug-only behind `ACDREAM_ENABLE_SKY_PES=1`.
|
||||
|
||||
Retail header at `acclient.h` line 35451 still documents the copied field:
|
||||
|
||||
```c
|
||||
struct CelestialPosition {
|
||||
|
|
@ -302,21 +305,24 @@ struct CelestialPosition {
|
|||
| 7 | 0x02000BA6 | 0x33000453 | 0.03–0.19 | early morning |
|
||||
| 17 | 0x02000589 | **0x3300042C** | **0.27–0.91** | **active during user's screenshot** |
|
||||
|
||||
acdream's geometry half is now wired (commit landing 2026-04-27 — `EnsureSetupUploaded` walks `Setup.Parts` for `0x020xxx` IDs). The dynamic visual half — emitting and animating the PES particles — is unimplemented and provides the actual aurora look. Phase E.3 already has data-only PES support per memory crib `project_session_2026_04_18.md`; this issue requires the runtime + visual half.
|
||||
acdream's geometry half is now wired (commit landing 2026-04-27 — `EnsureSetupUploaded` walks `Setup.Parts` for `0x020xxx` IDs). The remaining dynamic visual half is not `SkyObject.PesObjectId`; likely suspects are sky/weather mesh material state, texture transform/blending, or a separate weather/lightning subsystem outside `GameSky`.
|
||||
|
||||
**Implementation outline:**
|
||||
1. PES dat decode (already partially in `AcDream.Core.World.PesData` per Phase E.3).
|
||||
2. PES emitter runtime — schedule, spawn, advect, color-cycle, expire each particle.
|
||||
3. `SkyRenderer` integration — when `MakeObject` sees `pes_id != 0`, spawn the PES at the SkyObject's celestial position.
|
||||
4. PES vertex-sprite renderer — billboarded textured quads with additive blending and color cycling. Probably reuses the future general-purpose particle renderer (issue #L? — TBD).
|
||||
1. Keep `SkyObject.PesObjectId` parsed for diagnostics only.
|
||||
2. Compare retail/acdream material state for the active sky/weather GfxObj/Setup ids (`0x02000588`, `0x02000589`, `0x02000714`, `0x02000BA6`).
|
||||
3. Trace the named retail sky/weather draw path for texture transforms, translucency, diffusion, luminosity, and any non-GameSky weather effect dispatch.
|
||||
4. Only add a new runtime visual path once the decompile has an actual caller.
|
||||
|
||||
**Decomp pointers:**
|
||||
- `CPhysicsObj::InitPartArrayObject` decomp ~280484 — dispatches type 7 to Setup loader.
|
||||
- `CPartArray::CreateSetup` decomp ~287490 — Setup → Parts → optional PES wiring.
|
||||
- `SkyDesc::GetSky` named retail `0x00501ec0` — copies `SkyObject.default_pes_object` into `CelestialPosition.pes_id`.
|
||||
- `GameSky::CreateDeletePhysicsObjects` named retail `0x005073c0` — creates/updates sky objects from `gfx_id`, does not read `pes_id`.
|
||||
- `GameSky::MakeObject` named retail `0x00506ee0` — calls `CPhysicsObj::makeObject(gfx_id, 0, 0)`, no PES.
|
||||
- `GameSky::UseTime` named retail `0x005075b0` — updates frame/luminosity/diffusion/translucency, no PES.
|
||||
|
||||
**Files:**
|
||||
- `src/AcDream.Core/World/SkyDescLoader.cs` — `SkyObjectData` needs to carry `PesObjectId` (currently dropped on the floor).
|
||||
- `src/AcDream.App/Rendering/Sky/SkyRenderer.cs` — needs a particle-emission step alongside the per-SkyObject mesh draw.
|
||||
- `src/AcDream.Core/World/SkyDescLoader.cs` — carries `PesObjectId` for diagnostics.
|
||||
- `src/AcDream.App/Rendering/Sky/SkyRenderer.cs` — likely material/texture-transform parity work.
|
||||
- `src/AcDream.App/Rendering/GameWindow.cs` — sky-PES playback remains debug-only, disabled by default.
|
||||
|
||||
**Acceptance:** When retail shows aurora-style light play at a specific in-game time / weather, acdream shows a visually-comparable effect at the same time.
|
||||
|
||||
|
|
|
|||
|
|
@ -4,6 +4,14 @@
|
|||
**Filed:** 2026-04-27 (handoff from sky/weather session, branch merged at f7c9e88).
|
||||
**Worktree:** to be created at `.worktrees/phase-c1-particles` on branch `feature/phase-c1-particles`.
|
||||
|
||||
**2026-04-28 correction:** named-retail decompile disproves the sky-PES
|
||||
premise in this spec. `SkyDesc::GetSky` copies `default_pes_object` into
|
||||
`CelestialPosition.pes_id`, but `GameSky::CreateDeletePhysicsObjects`
|
||||
(`0x005073c0`), `GameSky::MakeObject` (`0x00506ee0`), and
|
||||
`GameSky::UseTime` (`0x005075b0`) never read it. C.1 remains valid as the
|
||||
generic PhysicsScript/particle renderer for real hooks, portals, smoke, etc.,
|
||||
but per-SkyObject PES playback is debug-only and disabled by default.
|
||||
|
||||
---
|
||||
|
||||
## What you're building
|
||||
|
|
|
|||
345
docs/research/2026-04-28-pes-pseudocode.md
Normal file
345
docs/research/2026-04-28-pes-pseudocode.md
Normal file
|
|
@ -0,0 +1,345 @@
|
|||
# Phase C.1 PES particle pseudocode
|
||||
|
||||
Retail sources:
|
||||
|
||||
- `docs/research/named-retail/acclient_2013_pseudo_c.txt`
|
||||
- `ParticleEmitterInfo::{GetRandom*,InitEnd,ShouldEmitParticle,UnPack}`
|
||||
at `0x005170d0..0x005179f0`
|
||||
- `ParticleManager::{CreateParticleEmitter,DestroyParticleEmitter,StopParticleEmitter}`
|
||||
at `0x0051b6c0..0x0051b7a0`
|
||||
- `Particle::{Update,Init}` and `ParticleEmitter::{EmitParticle,UpdateParticles}`
|
||||
at `0x0051b863..0x0051d400`
|
||||
- `PhysicsScript::{UnPack}` at `0x005218b0`
|
||||
- `CallPESHook::Execute`, `CreateParticleHook::Execute`,
|
||||
`DestroyParticleHook::Execute`, `StopParticleHook::Execute` at
|
||||
`0x00529eb0..0x0052a070`
|
||||
- `GameSky::{Draw,CreateDeletePhysicsObjects}` at
|
||||
`0x00506ff0..0x005075d0`
|
||||
- `docs/research/named-retail/acclient.h`
|
||||
- `EmitterType`, `ParticleType`
|
||||
- `ParticleEmitterInfo`, `Particle`, `ParticleEmitter`
|
||||
- `CreateParticleHook`, `CreateBlockingParticleHook`,
|
||||
`DestroyParticleHook`, `StopParticleHook`, `CallPESHook`
|
||||
- `CelestialPosition` with `pes_id`
|
||||
- Cross-checks:
|
||||
- `references/ACViewer/ACViewer/Physics/Particles/*`
|
||||
- `references/ACE/Source/ACE.DatLoader/Entity/ParticleEmitterInfo.cs`
|
||||
- `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/ParticleBatcher.cs`
|
||||
|
||||
## ParticleEmitterInfo
|
||||
|
||||
```text
|
||||
UnPack(reader):
|
||||
read id/header
|
||||
read unknown
|
||||
read emitter_type
|
||||
read particle_type
|
||||
read gfxobj_id
|
||||
read hw_gfxobj_id
|
||||
read birthrate
|
||||
read max_particles
|
||||
read initial_particles
|
||||
read total_particles
|
||||
read total_seconds
|
||||
read lifespan
|
||||
read lifespan_rand
|
||||
read offset_dir, min_offset, max_offset
|
||||
read A, min_a, max_a
|
||||
read B, min_b, max_b
|
||||
read C, min_c, max_c
|
||||
read start_scale, final_scale, scale_rand
|
||||
read start_trans, final_trans, trans_rand
|
||||
read is_parent_local
|
||||
|
||||
InitEnd():
|
||||
sorting_sphere.center = (0, 0, 0)
|
||||
sorting_sphere.radius = max(max_offset, max_a * lifespan)
|
||||
|
||||
RandomScale(base):
|
||||
value = base + RollDice(-1, 1) * scale_rand
|
||||
return clamp(value, 0.1, 10.0)
|
||||
|
||||
RandomTrans(base):
|
||||
value = base + RollDice(-1, 1) * trans_rand
|
||||
return clamp(value, 0.0, 1.0)
|
||||
|
||||
RandomLifespan():
|
||||
value = lifespan + RollDice(-1, 1) * lifespan_rand
|
||||
return max(value, 0.0)
|
||||
|
||||
RandomVector(dir, min, max):
|
||||
return dir * Random(min, max)
|
||||
|
||||
RandomOffset():
|
||||
v = random vector in [-1, 1]^3
|
||||
v = v - project(v, offset_dir)
|
||||
if length(v) is near zero:
|
||||
v = perpendicular fallback
|
||||
v = normalize(v)
|
||||
return v * Random(min_offset, max_offset)
|
||||
|
||||
ShouldEmitParticle(emitter):
|
||||
if total_particles != 0 and emitter.total_emitted >= total_particles:
|
||||
return false
|
||||
if emitter.num_particles >= max_particles:
|
||||
return false
|
||||
if emitter_type == BirthratePerSec:
|
||||
return Timer.cur_time - emitter.last_emit_time > birthrate
|
||||
if emitter_type == BirthratePerMeter:
|
||||
delta = emitter.last_emit_offset - emitter.current_parent_offset
|
||||
return dot(delta, delta) > birthrate * birthrate
|
||||
return false
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- Retail stores `birthrate` as seconds between emissions for
|
||||
`BirthratePerSec`, not particles per second.
|
||||
- Retail clamps start/final scale to `[0.1, 10]` and translucency to
|
||||
`[0, 1]`.
|
||||
- The named decomp shows final scale/trans add their own base values.
|
||||
ACE/ACViewer have a few copy-paste mistakes in these helpers; the decomp
|
||||
wins.
|
||||
|
||||
## ParticleManager and emitter lifetime
|
||||
|
||||
```text
|
||||
CreateParticleEmitter(parent, emitter_info_id, part_index, offset, requested_id):
|
||||
if requested_id != 0:
|
||||
remove existing emitter with requested_id
|
||||
info = Dat.Get(ParticleEmitterInfo, emitter_info_id)
|
||||
emitter = makeParticleEmitter()
|
||||
emitter.SetInfo(info)
|
||||
emitter.SetParenting(parent, part_index, offset)
|
||||
emitter.InitEnd()
|
||||
emitter.id = requested_id if requested_id != 0 else next_emitter_id++
|
||||
particle_table.add(emitter.id, emitter)
|
||||
return emitter.id
|
||||
|
||||
DestroyParticleEmitter(id):
|
||||
remove emitter id from particle_table
|
||||
|
||||
StopParticleEmitter(id):
|
||||
emitter.stopped = true
|
||||
|
||||
UpdateParticles():
|
||||
for each emitter:
|
||||
keep = emitter.UpdateParticles()
|
||||
if !keep:
|
||||
remove emitter
|
||||
```
|
||||
|
||||
`ParticleEmitter::EmitParticle` finds a free/recyclable slot, samples all
|
||||
random fields from the `ParticleEmitterInfo`, initializes a `Particle`, adds
|
||||
the particle part, and records `total_emitted`, `last_emit_time`, and
|
||||
`last_emit_offset`.
|
||||
|
||||
`ParticleEmitter::UpdateParticles`:
|
||||
|
||||
```text
|
||||
if drawable/parent is valid:
|
||||
for each live particle:
|
||||
parent_frame = parent-local ? current parent frame : particle.start_frame
|
||||
particle.Update(parent_frame, now, persistent)
|
||||
if particle.lifetime >= particle.lifespan:
|
||||
kill particle
|
||||
|
||||
while !stopped and info.ShouldEmitParticle(this):
|
||||
EmitParticle()
|
||||
|
||||
if total_seconds != 0 and now - creation_time > total_seconds:
|
||||
stopped = true
|
||||
if total_particles != 0 and total_emitted >= total_particles:
|
||||
stopped = true
|
||||
|
||||
return num_particles != 0 || !stopped
|
||||
```
|
||||
|
||||
## Particle integrators
|
||||
|
||||
Every particle computes position from age/lifetime, not by accumulating
|
||||
Euler steps. `parent.origin` below is the parent frame origin chosen by
|
||||
`is_parent_local`.
|
||||
|
||||
```text
|
||||
age = now - birthtime
|
||||
|
||||
Still:
|
||||
pos = parent.origin + offset
|
||||
|
||||
LocalVelocity, GlobalVelocity:
|
||||
pos = parent.origin + offset + age * A
|
||||
|
||||
ParabolicLVGA, ParabolicLVLA, ParabolicGVGA:
|
||||
pos = parent.origin + offset + age * A + 0.5 * age^2 * B
|
||||
|
||||
ParabolicLVGAGR, ParabolicLVLALR, ParabolicGVGAGR:
|
||||
frame = parent
|
||||
frame.origin += offset + age * A + 0.5 * age^2 * B
|
||||
frame.rotate_by(age * C)
|
||||
pos = frame.origin
|
||||
|
||||
Swarm:
|
||||
pos = parent.origin + offset + age * A
|
||||
pos.x += cos(age * B.x) * C.x
|
||||
pos.y += sin(age * B.y) * C.y
|
||||
pos.z += cos(age * B.z) * C.z
|
||||
|
||||
Explode:
|
||||
pos.x = parent.origin.x + offset.x + (age * B.x + C.x * A.x) * age
|
||||
pos.y = parent.origin.y + offset.y + (age * B.y + C.y * A.x) * age
|
||||
pos.z = parent.origin.z + offset.z + (age * B.z + C.z * A.x + A.z) * age
|
||||
|
||||
Implode:
|
||||
pos = parent.origin + offset + cos(A.x * age) * C + age^2 * B
|
||||
```
|
||||
|
||||
`Particle::Init` resolves vector spaces once at spawn:
|
||||
|
||||
```text
|
||||
offset = transform_local_vector(random_offset, start_frame)
|
||||
|
||||
LocalVelocity, ParabolicLVGA:
|
||||
A = local_to_global(A)
|
||||
|
||||
ParabolicLVLA:
|
||||
A = local_to_global(A)
|
||||
B = local_to_global(B)
|
||||
|
||||
ParabolicLVGAGR:
|
||||
A = local_to_global(A)
|
||||
C = C
|
||||
|
||||
Swarm:
|
||||
A = local_to_global(A)
|
||||
|
||||
Explode:
|
||||
A = A
|
||||
B = B
|
||||
C = normalized random direction scaled by the local C axes
|
||||
|
||||
Implode:
|
||||
A = A
|
||||
B = B
|
||||
offset *= C component-wise
|
||||
C = offset
|
||||
|
||||
ParabolicLVLALR:
|
||||
A = local_to_global(A)
|
||||
B = local_to_global(B)
|
||||
C = local_to_global(C)
|
||||
|
||||
ParabolicGVGA, GlobalVelocity:
|
||||
A/B/C remain global as applicable
|
||||
|
||||
ParabolicGVGAGR:
|
||||
A and B remain global
|
||||
C = C
|
||||
```
|
||||
|
||||
After motion:
|
||||
|
||||
```text
|
||||
t = clamp(age / lifespan, 0, 1)
|
||||
scale = lerp(start_scale, final_scale, t)
|
||||
trans = lerp(start_trans, final_trans, t)
|
||||
opacity = 1 - trans
|
||||
```
|
||||
|
||||
`StartTrans` / `FinalTrans` are transparency values, not source alpha.
|
||||
Retail sends the interpolated value to `PhysicsPart::SetTranslucency`; the
|
||||
render path uses its complement as opacity. WorldBuilder's particle renderer
|
||||
cross-check does the same (`opacity = 1 - currentTrans`).
|
||||
|
||||
## PhysicsScript and hooks
|
||||
|
||||
`PhysicsScript::UnPack` reads ordered `(start_time, hook)` entries and sorts
|
||||
them by start time. The runner keeps active script instances keyed by
|
||||
`(script_id, entity_id)` and fires all hooks whose `start_time <= elapsed`.
|
||||
|
||||
Hook execution:
|
||||
|
||||
```text
|
||||
CreateParticleHook:
|
||||
parent.create_particle_emitter(emitter_info_id, part_index, offset, emitter_id)
|
||||
|
||||
CreateBlockingParticleHook:
|
||||
same particle creation path, plus sequencer blocking semantics
|
||||
|
||||
DestroyParticleHook:
|
||||
parent.destroy_particle_emitter(emitter_id)
|
||||
|
||||
StopParticleHook:
|
||||
parent.stop_particle_emitter(emitter_id)
|
||||
|
||||
CallPESHook:
|
||||
parent.CallPES(pes_id, pause)
|
||||
```
|
||||
|
||||
The C.1 implementation keeps hook dispatch in Core and renders the resulting
|
||||
particles in App. Nested `CallPESHook` stays in `PhysicsScriptRunner`, while
|
||||
`ParticleHookSink` converts create/destroy/stop hooks into runtime emitter
|
||||
handles.
|
||||
|
||||
## Sky integration
|
||||
|
||||
`CelestialPosition` has both `gfx_id` and `pes_id`. Retail sky object
|
||||
creation copies `properties` and draws two sky cells. A named-retail recheck
|
||||
on 2026-04-28 corrected the original C.1 assumption:
|
||||
|
||||
```text
|
||||
SkyDesc::GetSky (0x00501ec0):
|
||||
copy SkyObject.gfx_id into CelestialPosition.gfx_id
|
||||
copy SkyObject.default_pes_object into CelestialPosition.pes_id
|
||||
copy properties / rotate / arc angle / tex velocity
|
||||
|
||||
GameSky.CreateDeletePhysicsObjects (0x005073c0):
|
||||
for each visible CelestialPosition:
|
||||
post_scene = (properties & 0x01) != 0
|
||||
make/update sky gfx object from gfx_id in before/after cell
|
||||
do not read pes_id
|
||||
|
||||
GameSky.MakeObject (0x00506ee0):
|
||||
CPhysicsObj::makeObject(gfx_id, 0, 0)
|
||||
set texture velocity
|
||||
|
||||
GameSky.UseTime (0x005075b0):
|
||||
CreateDeletePhysicsObjects()
|
||||
CalcFrame()
|
||||
set_frame / luminosity / diffusion / translucency
|
||||
do not read pes_id
|
||||
|
||||
GameSky.Draw(post_scene):
|
||||
if post_scene == false:
|
||||
draw before_sky_cell
|
||||
else:
|
||||
draw after_sky_cell
|
||||
```
|
||||
|
||||
The sky renderer must preserve the existing `0x01` pre/post split for sky
|
||||
meshes. `SkyObject.default_pes_object` is parsed and retained for diagnostics,
|
||||
but it is not a retail render-path particle source. In acdream the experimental
|
||||
sky-PES path is therefore gated behind `ACDREAM_ENABLE_SKY_PES=1` and disabled
|
||||
for normal visual comparison.
|
||||
|
||||
## GL rendering
|
||||
|
||||
WorldBuilder's `ParticleBatcher` confirms the GL-side policy:
|
||||
|
||||
```text
|
||||
collect live billboard instances
|
||||
sort back-to-front by camera distance for alpha blending
|
||||
depth test enabled
|
||||
depth writes disabled
|
||||
cull disabled
|
||||
blend SrcAlpha/OneMinusSrcAlpha for alpha
|
||||
blend SrcAlpha/One for additive
|
||||
stream dynamic instance VBO
|
||||
draw instanced unit quads
|
||||
```
|
||||
|
||||
C.1 keeps that policy and splits draw calls by particle render pass:
|
||||
|
||||
- pre-scene sky particles after the pre-scene sky meshes
|
||||
- scene particles after opaque world/static objects
|
||||
- post-scene sky particles after post-scene sky/weather meshes
|
||||
97
docs/research/2026-04-28-sky-cloud-material-trace.md
Normal file
97
docs/research/2026-04-28-sky-cloud-material-trace.md
Normal file
|
|
@ -0,0 +1,97 @@
|
|||
# 2026-04-28 Sky Cloud Material Trace
|
||||
|
||||
Context: Phase C.1 originally treated the Rainy/Cloudy sky visual as a
|
||||
SkyObject PES problem. Retail named-decomp and dat inspection disprove that
|
||||
for the broad cloud/ray layer.
|
||||
|
||||
## Retail Trace
|
||||
|
||||
- `LScape::draw` (`0x00506330`) calls `GameSky::Draw(0)` before terrain and
|
||||
`GameSky::Draw(1)` after terrain.
|
||||
- `SkyDesc::GetSky` copies `pes_id`, but `GameSky::CreateDeletePhysicsObjects`
|
||||
compares/replaces only `gfx_id` and calls `GameSky::MakeObject(gfx_id, ...)`.
|
||||
The sky object PES id is not part of retail `GameSky` rendering.
|
||||
- `GameSky::UseTime` applies keyframe replace fields to instantiated sky
|
||||
objects:
|
||||
- `0x005076e1`: `CPhysicsObj::SetLuminosity(luminosity * 0.01)`
|
||||
- `0x00507715`: `CPhysicsObj::SetDiffusion(max_bright * 0.01)`
|
||||
- `0x00507747`: `CPhysicsObj::SetTranslucency(transparent * 0.01)`
|
||||
- `CMaterial::SetTranslucencySimple` (`0x005396f0`) writes material alpha as
|
||||
`1 - translucency`.
|
||||
- `CMaterial::SetDiffuseSimple` (`0x00539750`) writes material diffuse RGB.
|
||||
Therefore `SkyObjectReplace.MaxBright` is diffuse, not an emissive cap.
|
||||
- `D3DPolyRender::SetSurface` (`0x0059c4d0`) disables fixed-function fog alpha
|
||||
whenever the raw `SurfaceType.Additive` bit is set (`0x0059c882`), even when
|
||||
the earlier `Translucent + ClipMap` branch forces normal alpha blending.
|
||||
|
||||
## Dat Trace
|
||||
|
||||
The broad Rainy/Cloudy layer is `GfxObj 0x01004C35`, not one of the tiny
|
||||
`0x020xxxxx` setup anchors:
|
||||
|
||||
- `0x01004C35`: huge sky mesh, bbox roughly `20175 x 20175 x 1180`, UVs tile
|
||||
across the sheet.
|
||||
- Surface `0x08000023`: `Base1ClipMap | Translucent | Alpha | Additive`
|
||||
(`0x00010114`), `Translucency=0.25`, `Luminosity=0`, `Diffuse=1`.
|
||||
- Texture `0x060037AF`: 256x256 A8R8G8B8 cloud/ray texture.
|
||||
|
||||
The setup ids observed in Rainy groups (`0x02000588`, `0x02000589`,
|
||||
`0x02000BA6`, `0x02000714`) are one-part dummy anchors with tiny `0x010001EC`
|
||||
geometry and default scripts/PES for sounds/flashes. They are not the broad
|
||||
cloud layer.
|
||||
|
||||
## Port Consequences
|
||||
|
||||
- Keep per-SkyObject PES rendering debug-only until another retail path proves
|
||||
it is used.
|
||||
- Render `0x08000023` as final alpha blend because retail's translucent/clipmap
|
||||
branch overrides the raw additive blend.
|
||||
- Still disable sky fog for that surface because retail keys fog-alpha disable
|
||||
off the raw `Additive` bit.
|
||||
- Route `MaxBright` to diffuse (`uDiffuseFactor`) and `Luminosity` to emissive.
|
||||
- Use a final opacity multiplier for material/surface transparency before the
|
||||
fragment alpha write; dynamic keyframe transparency remains `1 - value`.
|
||||
|
||||
## WorldBuilder Cross-Check
|
||||
|
||||
Cloned upstream `https://github.com/Chorizite/WorldBuilder.git` at commit
|
||||
`167788be6fce65f5ebe79eef07a0b7d28bd7aa81`. Its
|
||||
`Chorizite.OpenGLSDLBackend/Lib/SkyboxRenderManager.cs` renders sky objects
|
||||
camera-centered with depth off, but it is not a faithful retail oracle for sky
|
||||
tint: `GameScene.cs` has the skybox render call commented out, the manager
|
||||
always selects `DayGroups[0]`, and it uploads `SunlightColor = Vector3.Zero`
|
||||
/ `AmbientColor = Vector3.One` for sky. `RegionInfo.cs` interpolates
|
||||
DayGroup[0] lighting for terrain/world objects, not the active retail
|
||||
DayGroup/weather sky.
|
||||
|
||||
That explains why WorldBuilder cannot answer the missing green/purple Rainy
|
||||
sky tint directly. The actionable lesson is narrower: do not fog-paint the
|
||||
raw-additive cloud sheet itself. In acdream, non-additive sky layers now receive
|
||||
the keyframe fog tint so the broad background wash appears behind clouds, while
|
||||
surfaces with the raw Additive bit (notably `0x08000023`) keep fixed-function
|
||||
fog disabled and preserve the pink cloud/ray detail.
|
||||
|
||||
WorldBuilder's regular object path does collect `Setup.DefaultScript`
|
||||
particle hooks (`ObjectMeshManager.CollectEmittersFromScript`) and instantiates
|
||||
them via `ObjectRenderManagerBase`, but its skybox manager does not use that
|
||||
setup/particle path for SkyObjects. Dat inspection also showed the canonical
|
||||
Rainy default script target `0x3300042C` is a sound-loop chain (`SoundTweaked`
|
||||
+ `CallPES`), not the broad green tint or cloud ray layer.
|
||||
|
||||
Additional renderer lessons from upstream WorldBuilder:
|
||||
|
||||
- Particle blend is material-derived. `ParticleEmitterInfo` does not carry an
|
||||
additive flag; WorldBuilder reads `ObjectRenderData.Batches[0].IsAdditive`
|
||||
from the particle GfxObj surface. acdream now leaves DAT emitters non-additive
|
||||
by default and resolves particle blend from the selected particle surface.
|
||||
- Particles must be globally sorted back-to-front before drawing. Sorting only
|
||||
inside per-texture dictionaries can reorder translucent particles whenever
|
||||
multiple textures/blend states are active.
|
||||
- Particle quads come from the authored particle GfxObj bounds. Degenerate
|
||||
extents fall back to `1.0`, and point-sprite degrade mode applies a `0.9`
|
||||
base scale.
|
||||
- Texture decoding must try highres `RenderSurface` records after portal lookup
|
||||
and must zero alpha for black pixels on compressed clipmap textures.
|
||||
- WorldBuilder tracks UV wrap and cull mode per object batch. acdream's sky path
|
||||
already uses authored UV wrap, but shared object rendering still needs the
|
||||
same metadata carried through a later C.4 pass.
|
||||
Loading…
Add table
Add a link
Reference in a new issue