Talk:EFFDIR

EFFDIR is a compiled binary effect program, not a hand-authored data format.

In SimCity 4, visual, audio, and camera effects are authored in a text-based DSL (.fx files), parsed and validated by an effects compiler, and serialized into the EFFDIR resource. The game at runtime loads and executes this compiled representation directly.

EFFDIR is therefore best understood as compiler output, not a script or configuration file.

high-level architecture

The effects system consists of five distinct stages, all present in the retail executable:

Authoring language Text-based .fx files (effects DSL).

Front-end parser cSC4EffectsParser

Enforces grammar and semantic rules

Builds an in-memory effect graph

Resolves names, probabilities, LODs, transforms

Rejects invalid constructs (e.g. prob outside select)

Intermediate representation (IR) A graph of concrete C++ objects:

cSC4ParticlesDescription

cSC4DecalDescription

cSC4ShakeDescription

cSC4LightDescription

cSC4EffectDescription

etc.

Compiler backend / serializer cSC4EffectsResource::Write

Serializes the IR into a versioned binary format

Writes strict counts, ordering, and sentinels

Produces the EFFDIR DBPF resource

Runtime loader and executor

cSC4EffectsResource::Read loads compiled EFFDIR

cSC4EffectsManager::sCreateEffect instantiates effects by name

No parsing, validation, or interpretation occurs at runtime

canonical EFFDIR TGI

The main Maxis effect directory has:

type: 0xEA5118B0

group: 0xEA5118B1

instance: 0x00000001

The engine explicitly supports multiple EFFDIR resources. All resources of type 0xEA5118B0 are enumerated and loaded; instance 1 is treated as the canonical base, others extend or override it.

versioning

EFFDIR is explicitly versioned:

vanilla SC4: version 3.1

Rush Hour / Deluxe: version 4.2

The version is written by the compiler and read by the loader. Certain sections (e.g. dynamic particles) only exist in version 4.

relationship to .fx files

.fx files are the source language

EFFDIR is the compiled binary

Both populate the same runtime structures

In retail gameplay, EFFDIR is loaded first. Parsing .fx files is a fallback/debug path controlled by the packedeffects framework property. Once loaded, the engine does not distinguish between effects originating from .fx or EFFDIR.

section model (correct interpretation)

EFFDIR does not contain explicit “section IDs”. Instead, the format is defined by a fixed write order in cSC4EffectsResource::Write. Each logical section is a vector written with a preceding count.

The write order is the authoritative specification.

compiled sections (in write order)

particle descriptions cSC4ParticlesDescription

particle flag bitsets bitset<7>

particle integer metadata

particle curve vectors

brush descriptions cSC4BrushDescription

attractors / generators cSC4AttractorDescription

scrubbers / destructive effects cSC4ScrubberDescription

sequences / select groups cSC4SequenceDescription

sounds cSC4SoundDescription

camera effects cSC4CameraDescription

dynamic particles (version 4 only) cSC4DynamicParticleDescription

effect bindings cSC4EffectDescription (this corresponds to “section 12” in older documentation)

name → effect index table (string lookup table, terminated by "end", 0xFFFFFFFF) (corresponds to “section 13”)

tool / resource links (optional)

class ID links

collision / radius data

All counts, ordering, and sentinels are written explicitly by the compiler backend.

effect binding and execution

At runtime:

Effects are instantiated by name

Name lookup is a hashtable built from section 13

All references are pre-resolved indices

No script execution, branching, or parsing occurs

This is why effects can be created cheaply during disasters, UDI, and animations.

select groups and probability

select { ... } blocks in .fx compile into sequence descriptions with weighted probabilities.

Important constraints enforced at compile time:

prob is only valid inside select

lod is forbidden inside select

probabilities are converted to fixed-point thresholds (uint16)

These rules explain the structure historically described as “randomized picks”.

transforms, LOD, and flags

Effect transforms (offset, rotation, scale):

are compiled into matrices, not stored as angles

rotations are normalized turns (× 2π)

flags indicate which transforms are present

LOD ranges are stored as inclusive–exclusive zoom bounds

This explains many previously “mysterious” fields in section 12.

important corrections to older documentation

EFFDIR is not hand-authored

“section end markers” are not magic constants; they are a byproduct of serialized vectors and sentinels

many DWORDs previously described as integers are actually Float32 values

section numbers are conceptual, not stored in the file

EFFDIR is intentionally designed, versioned, and compiler-generated

definitive conclusion

EFFDIR is the compiled output of a Maxis-authored effects compiler:

.fx is the source language

cSC4EffectsParser is the front-end

cSC4EffectsResource::Write is the compiler backend

cSC4EffectsResource::Read is the loader

runtime execution assumes fully validated, prelinked data

The correct way to document EFFDIR is as a compiler output format, not as an ad-hoc binary blob.

This understanding fully explains the structure, constraints, and behavior observed in SimCity 4 effects.