dayz-particles

Reference for creating and playing custom DayZ particle effects without Workbench: .ptc and .emat files, .edds sprites, the Particle, ParticleManager and SEffectManager script API, and the vanilla par

SKILL.md

GitHub

DayZ particle effects

Follow skills/_shared/dayz-conventions.md. This skill is reference only; it runs no scripts, so there is no preflight gate.

What to read

Task Read
Write or edit a .ptc (emitters, curves, every property) references/ptc-format-reference.md
Write or edit an .emat, pick a vanilla material or sprite GUID references/emat-format-reference.md
Play, stop or tune particles from script references/script-api-reference.md
Wire particles into a device (toggle, one-shot, cleanup) references/integration-patterns.md
Find a vanilla particle to reuse references/vanilla-particle-catalog.md

File layers

Layer Format Purpose
.ptc Plain text Effect: one EffectDef with one or more EmitorDef blocks
.emat Plain text Material: texture ref, shader (Particle or ParticleSprite), blend mode
.edds DDS renamed Billboard sprite texture
.meta Plain text Written by Workbench; not needed at mod runtime

Because .ptc and .emat are plain text, they can be written by hand or generated by a script.

GUID references

Resources reference each other as {HEXGUID}relative/path.ext.

  • Mod .ptc to vanilla .emat, or mod .emat to vanilla .edds: copy the vanilla GUID plus path, exactly as vanilla files do.
  • Mod .ptc to mod .emat: path only; mod-owned resources resolve by PBO path.

Path-only references resolve: vanilla itself ships one. P:\graphics\particles\contaminated_area_gas_around_tiny.ptc:13 has Material "Graphics/Particles/materials/enviroment/water_splash_01_em.emat" with no GUID, and that effect is registered at P:\scripts\3_game\particles\particlelist.c:316 and played by the contaminated area (P:\scripts\4_world\classes\contaminatedarea\effectarea.c:80). Every vanilla .emat texture reference carries a GUID, so for vanilla resources copy GUID plus path to match vanilla, and the path alone is a working fallback.

Script API in one screen

  • Particle (legacy): Particle.PlayOnObject(id, parent, localPos, localOri, forceWorldRot), Particle.PlayInWorld(id, worldPos). Non-looping particles delete themselves.
  • ParticleSource extends Particle: native-backed, auto-destroy flags (ON_END, ON_STOP, ALL, NONE), DisableAutoDestroy(), ResetParticle().
  • ParticleManager.GetInstance(): global pool of 10000 ParticleSource objects, created only when not on a headless or dedicated server, so it returns null there (P:\scripts\3_game\particles\particlemanager\particlemanager.c:25 and :63-65). Null-check it.
  • SEffectManager.PlayOnObject(effect, parent, pos, ori) for particle plus sound; clean up only with SEffectManager.DestroyEffect(effect).
  • Control: StopParticle(flags) fades out by default (StopParticleFlags.IMMEDIATE removes at once, PAUSE freezes), SetParameter(emitter, EmitorParam.X, value) with -1 for all emitters, ScaleParticleParamFromOriginal(EmitorParam.SIZE, 0.5).

Registering custom particles

MyMod/
  data/particles/mymod_water_spray.ptc
  data/particles/materials/mymod_blue_water.emat   (optional)
  scripts/3_Game/MyMod_ParticleList.c
modded class ParticleList
{
    static const int MYMOD_WATER_SPRAY = RegisterParticle("MyMod/data/particles/", "mymod_water_spray");
};

Packing: /dayz-build-pbo already packs .ptc, .emat and .edds (its include filter is skills/dayz-build-pbo/include.lst), so no change is needed. Only with a custom AddonBuilder setup, add whichever of *.ptc;*.emat;*.edds are missing to your existing include filter; do not replace the filter, or other file types such as .p3d models are dropped from the PBO.

Pitfalls

  1. Particles are client-only. Guard with a runtime GetGame().IsHeadlessOrDedicatedServer() check, as every pattern in references/integration-patterns.md does (Pattern A shows it first). It is the same gate vanilla's particle pool uses (P:\scripts\3_game\particles\particlemanager\particlemanager.c:65); IsDedicatedServer() alone lets the code run on a headless client. Vanilla PowerGeneratorBase gates its smoke on IsClient() || !IsMultiplayer() instead (P:\scripts\4_world\entities\itembase\powergenerator.c:196); Pattern D, which follows that class, still uses IsHeadlessOrDedicatedServer() so one gate covers every pattern. Do not use #ifndef SERVER: testing runs DayZDiag_x64.exe for both ends, and a compile-time define does not separate them.
  2. Looping particles (Repeat 1) never end on their own. Stop them and null the reference; clean up in EEDelete, power-off and the destructor.
  3. Stop() fades out gradually; use StopParticleFlags.IMMEDIATE for instant removal.
  4. ObjectDelete(particle) is valid only for a ParticleSource with DisableAutoDestroy().
  5. Give .ptc files a mod prefix (mymod_) so filenames don't collide across mods.
  6. AIR_RESISTANCE controls how fast smoke rises; use forceWorldRot = true for smoke and steam that should always rise straight up.
  7. EffectTime is the master-curve cycle; Repeat loops the whole effect. A one-shot (Repeat 0) plays once for EffectTime.