test/agent-skills/11-gfx-to-particle-system.md

GFX to Particle System Conversion Notes

Key Difference: Scale Handling

C++ (Original)

In the original C++ engine, GFX files (.gfx) were custom Angelica 3D effect objects (A3DGFXEx). Scale was applied programmatically via code:

// C++ — scale set by code on each GFX instance
pGfx->SetScale(fFlyGfxScale);
pGfx->SetActualScale(pHitGfx->GetScale() * 2.0f); // e.g. critical hit 2x

Two scale fields existed per composer:

• m_fFlyGfxScale — fly GFX scale multiplier
• m_fHitGfxScale — hit GFX scale multiplier

These were also used with m_bRelScl and m_fDefTarScl for relative-to-target scaling:

if (m_bRelScl)
    fScale = GetTargetScale(target) / m_fDefTarScl * m_fHitGfxScale;
else
    fScale = m_fHitGfxScale;

Unity (Current)

In Unity, all .gfx files have been converted to Particle Systems (prefabs with ParticleSystem components).

Scale is NOT needed in code because:

1. Particle Systems define their own size/scale in the prefab inspector
2. Visual size is controlled by Start Size, Size Over Lifetime, etc. within the particle system
3. The particle system already looks correct at its authored scale when instantiated

What Was Removed

• m_fFlyGfxScale and m_fHitGfxScale fields from A3DSkillGfxComposer
• fFlyGfxScale and fHitGfxScale parameters from AddSkillGfxEvent() and AddOneSkillGfxEvent()
• Scale calculation in AddOneTarget() (the if (m_bRelScl) block)
• pGfx.SetScale() calls (were already commented out)

What Was Kept

• m_bRelScl and m_fDefTarScl — kept in SkillStub and A3DSkillGfxComposer for potential future use (e.g., if we ever want relative scaling on huge bosses)

Rule for Future Development

DO NOT add GFX scale parameters back into the code pipeline. If scale adjustment is needed for specific skills (e.g., boss skills should be bigger), use Unity's built-in Transform scale on the instantiated prefab, or create a variant prefab with different particle sizes. Do not try to replicate the C++ SetScale() pattern.

GFX Loading Path

C++:   A3DGFXEx* pGfx = LoadGfx(pDevice, "gfx/path/to/effect.gfx");
Unity: GameObject prefab = await Addressables.LoadAssetAsync<GameObject>("gfx/path/to/effect");
       GameObject instance = Instantiate(prefab, position, rotation);

The Addressable address uses the same path as C++ (minus the .gfx extension), prefixed with gfx/.