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.mdskills/dayz-particles/SKILL.md
GitHubDayZ 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
.ptcto vanilla.emat, or mod.ematto vanilla.edds: copy the vanilla GUID plus path, exactly as vanilla files do. - Mod
.ptcto 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.ParticleSourceextendsParticle: native-backed, auto-destroy flags (ON_END,ON_STOP,ALL,NONE),DisableAutoDestroy(),ResetParticle().ParticleManager.GetInstance(): global pool of 10000ParticleSourceobjects, created only when not on a headless or dedicated server, so it returns null there (P:\scripts\3_game\particles\particlemanager\particlemanager.c:25and:63-65). Null-check it.SEffectManager.PlayOnObject(effect, parent, pos, ori)for particle plus sound; clean up only withSEffectManager.DestroyEffect(effect).- Control:
StopParticle(flags)fades out by default (StopParticleFlags.IMMEDIATEremoves at once,PAUSEfreezes),SetParameter(emitter, EmitorParam.X, value)with-1for 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
- Particles are client-only. Guard with a runtime
GetGame().IsHeadlessOrDedicatedServer()check, as every pattern inreferences/integration-patterns.mddoes (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. VanillaPowerGeneratorBasegates its smoke onIsClient() || !IsMultiplayer()instead (P:\scripts\4_world\entities\itembase\powergenerator.c:196); Pattern D, which follows that class, still usesIsHeadlessOrDedicatedServer()so one gate covers every pattern. Do not use#ifndef SERVER: testing runsDayZDiag_x64.exefor both ends, and a compile-time define does not separate them. - Looping particles (
Repeat 1) never end on their own. Stop them and null the reference; clean up inEEDelete, power-off and the destructor. Stop()fades out gradually; useStopParticleFlags.IMMEDIATEfor instant removal.ObjectDelete(particle)is valid only for aParticleSourcewithDisableAutoDestroy().- Give
.ptcfiles a mod prefix (mymod_) so filenames don't collide across mods. AIR_RESISTANCEcontrols how fast smoke rises; useforceWorldRot = truefor smoke and steam that should always rise straight up.EffectTimeis the master-curve cycle;Repeatloops the whole effect. A one-shot (Repeat 0) plays once forEffectTime.