Visual effects system: particles and animations

The visual effects system handles every particle, aura, glow, and animated overlay in Paper Mario — from the dust cloud when Mario lands to the elaborate star-spirit release sequences. Each effect is implemented as a standalone C file under src/effects/ and registered through src/effects.yaml, which the build system uses to generate spawn-function declarations and the effects dispatch table.

How effects are defined

Each effect lives in its own source file in src/effects/. An effect file typically contains:

An FXData struct (declared in include/effects.h) that holds per-instance state — position, velocity, timer, colour, and so on.
An init function that allocates the instance and sets its initial state.
An update function called every frame.
An appendGfx function that writes the RDP display list for rendering.

The effect is registered in src/effects.yaml with a name, its argument signature, and optional shared graphics (gfx). The build system generates a fx_<name>(...) spawn function for each entry.

Example YAML entries

- name: big_smoke_puff
  args: f32, f32, f32      # x, y, z
  void: True               # spawn function returns void

- name: landing_dust
  args: s32, f32, f32, f32, f32
  void: True

- name: flower_splash
  args: f32, f32, f32, f32
  gfx: flower_splash_trail # shares graphics with flower_trail
  void: True

- name: star
  args: s32, f32, f32, f32, f32, f32, f32, f32
  # no void: returns EffectInstance*

When void is True, the spawn function returns nothing. When omitted, it returns a pointer to the live EffectInstance so the caller can track or destroy the effect.

Spawning an effect

From C code, you call the generated spawn function directly. From an EVT script, effects are spawned through wrapper callables or directly via ApiStatus functions defined in the battle and map script APIs.

Example data struct from `include/effects.h`

// Used by both flower_splash and flower_trail effects
typedef struct FlowerFXData {
    /* 0x00 */ s32 alive;
    /* 0x04 */ u16 triggeredByNpc;
    /* 0x06 */ s16 timeLeft;
    /* 0x08 */ u8 primAlpha;
    /* 0x09 */ s8 useAltColor;
    /* 0x0C */ Vec3f pos;
    /* 0x18 */ Vec3f scale;
    /* 0x24 */ Vec3f rot;
    /* 0x30 */ Mtx transformMtx;
    /* 0x70 */ f32 velScaleA;
    /* 0x74 */ f32 velScaleB;
    /* 0x78 */ f32 visibilityAmt;
    /* 0x90 */ VecXZf vel;
} FlowerFXData; // size = 0x98

Many FX data structs in include/effects.h still contain fields prefixed unk_ — these are part of the ongoing decompilation effort. If you identify a field, add a named declaration and open a pull request.

Effect categories

The 120+ effects in src/effects/ fall into several functional groups.

Movement and dust effects

These fire when characters move, land, or interact with the environment.

File	Effect
`landing_dust.c`	Dust puff on landing
`walking_dust.c`	Footstep dust while walking
`footprint.c`	Footprint decal on soft ground
`big_smoke_puff.c`	Large smoke cloud
`cloud_puff.c`	Small cloud puff
`cloud_trail.c`	Trailing cloud effect
`smoke_burst.c`	Sudden smoke burst
`smoke_impact.c`	Smoke on impact
`smoke_ring.c`	Ring-shaped smoke
`steam_burst.c`	Steam burst (lava, etc.)

Combat and damage effects

These accompany attacks, status inflictions, and hit reactions.

File	Effect
`damage_indicator.c`	Floating damage number
`damage_stars.c`	Stars that orbit after taking damage
`attack_result_text.c`	”Nice!”, “Good”, “Great!” text
`explosion.c`	General explosion
`blast.c`	Directional blast
`green_impact.c`	Green impact flash
`red_impact.c`	Red impact flash
`shockwave.c`	Radial shockwave ring
`energy_shockwave.c`	Energy-type shockwave
`ring_blast.c`	Ring-shaped blast
`flashing_box_shockwave.c`	Box flash on shockwave
`lightning_bolt.c`	Lightning bolt strike
`lightning.c`	Lightning effect
`thunderbolt_ring.c`	Ring from thunderbolt
`fire_breath.c`	Fire breath stream
`cold_breath.c`	Cold breath stream
`huff_puff_breath.c`	Huff Puff specific breath
`ice_pillar.c`	Ice pillar rising
`ice_shard.c`	Ice shard shrapnel
`throw_spiny.c`	Spiny thrown projectile

Status and buff effects

These indicate ongoing status conditions or stat changes.

File	Effect
`aura.c`	General aura glow around actor
`spiky_white_aura.c`	Spiky white aura (spiked)
`partner_buff.c`	Partner power-up aura
`debuff.c`	Debuff indicator
`disable_x.c`	Disable X mark
`static_status.c`	Paralysis static crackle
`snaking_static.c`	Snaking static electricity
`sleep_bubble.c`	Sleep bubble floating
`sweat.c`	Sweat drops
`emote.c`	NPC emote icon (! ? ♥ etc.)
`stop_watch.c`	Stop-watch freeze indicator
`stat_change.c`	Stat change arrow indicator
`recover.c`	Recovery sparkle

Sparkle, star, and glow effects

File	Effect
`sparkles.c`	General sparkle burst
`star.c`	Single star
`stars_burst.c`	Stars bursting outward
`stars_orbiting.c`	Stars orbiting a point
`stars_shimmer.c`	Shimmering stars
`stars_spread.c`	Stars spreading outward
`star_outline.c`	Star outline icon
`shiny_flare.c`	Shiny lens flare
`lens_flare.c`	Camera lens flare
`shimmer_burst.c`	Shimmer burst
`shimmer_wave.c`	Shimmer wave
`radial_shimmer.c`	Radial shimmer pulse
`pink_sparkles.c`	Pink sparkles
`small_gold_sparkle.c`	Small gold sparkle
`light_rays.c`	God-ray light shafts
`bulb_glow.c`	Bulb glow

Environment and weather effects

File	Effect
`snowfall.c`	Falling snow field
`snowflake.c`	Individual snowflake
`big_snowflakes.c`	Large snowflakes
`falling_leaves.c`	Falling autumn leaves
`drop_leaves.c`	Leaves dropping from a point
`windy_leaves.c`	Leaves blown by wind
`butterflies.c`	Butterfly swarm
`underwater.c`	Underwater bubble ambience
`water_splash.c`	Water splash
`water_fountain.c`	Water fountain arc
`waterfall.c`	Waterfall curtain
`water_block.c`	Water block entity effect
`sun.c`	Sun disc
`moving_cloud.c`	Scrolling cloud
`floating_cloud_puff.c`	Floating cloud puff
`flame.c`	Flame (candle / torch)
`embers.c`	Floating embers
`fire_flower.c`	Fire flower bloom
`motion_blur_flame.c`	Motion-blurred flame

Cutscene and UI effects

File	Effect
`chapter_change.c`	Chapter title card
`confetti.c`	Confetti shower
`firework.c`	Firework burst
`firework_rocket.c`	Firework rocket trail
`ending_decals.c`	Decals used in the ending sequence
`spirit_card.c`	Star spirit card
`star_spirits_energy.c`	Star spirits release energy
`peach_star_beam.c`	Peach’s star beam
`got_item_outline.c`	Item pickup outline glow
`tattle_window.c`	Goombario tattle popup
`music_note.c`	Floating music note
`lil_oink.c`	Li’l Oink piglet effect
`merlin_house_stars.c`	Stars in Merlon’s house
`balloon.c`	Inflating balloon
`shape_spell.c`	Kammy’s shape-spell effect

Quiz show and parade effects

File	Effect
`quizmo_answer.c`	Quiz answer flash
`quizmo_assistant.c`	Quiz assistant sparkle
`quizmo_audience.c`	Audience member effect
`quizmo_stage.c`	Quiz stage environment
`hieroglyphs.c`	Hieroglyph tiles
`snowman_doll.c`	Snowman doll prop
`lil_oink.c`	Li’l Oink farm piglet

Energy and magic effects

File	Effect
`gather_energy_pink.c`	Pink energy gather
`gather_magic.c`	Magic energy gather
`energy_in_out.c`	Energy pulse in/out
`energy_orb_wave.c`	Energy orb wave
`radiating_energy_orb.c`	Radiating energy orb
`purple_ring.c`	Purple ring pulse
`rising_bubble.c`	Rising bubble
`floating_rock.c`	Floating rock fragment
`shattering_stones.c`	Shattering stone fragments
`bombette_breaking.c`	Bombette explosion debris
`breaking_junk.c`	Breaking junk particles
`chomp_drop.c`	Chain Chomp drop impact
`whirlwind.c`	Whirlwind vortex
`squirt.c`	Squirt stream
`tubba_heart_attack.c`	Tubba Blubba heart effect
`fright_jar.c`	Fright Jar effect

Unidentified effects

A small number of effects are not yet named in the decompilation:

File	Notes
`effect_3D.c`	3D geometry-based effect, type unknown
`effect_46.c`	Effect slot 46, content not yet identified
`effect_63.c`	Effect slot 63
`effect_65.c`	Effect slot 65
`effect_75.c`	Effect slot 75
`effect_86.c`	Effect slot 86
`something_rotating.c`	Rotating object effect, purpose unclear

If you identify one of these effects by cross-referencing the decompiled call sites, rename the file, add a proper name to src/effects.yaml, and update include/effects.h with a named FX data struct.

NPCs and entities

NPC decorations use the effects system — see how they attach to the Npc struct.

Audio system

Many effects trigger sound — see the audio API used alongside effect spawning.

Get Started

Contributing

EVT Scripting

Game Systems

Data Reference

Visual effects system: particles and animations

How effects are defined

Example YAML entries

Spawning an effect

Example data struct from `include/effects.h`

Effect categories

Unidentified effects

NPCs and entities

Audio system

Build docs developers (and LLMs) love

Get Started

Contributing

EVT Scripting

Game Systems

Data Reference

Documentation Index

​How effects are defined

​Example YAML entries

​Spawning an effect

​Example data struct from include/effects.h

​Effect categories

​Unidentified effects

NPCs and entities

Audio system

Build docs developers (and LLMs) love

How effects are defined

Example YAML entries

Spawning an effect

Example data struct from `include/effects.h`

Effect categories

Unidentified effects