Fission SDK · C++ technical reference
Every layer/entity-name prefix registered by the Fission entity factories — gameplay pieces, cutters, particles, collectables, presentation and scene-structure layers — what each one means, and the animation, sound and particle files associated with it.
A Fission scene is built from named layers. Every entity factory (fsCEntityFactory and its game-specific subclasses, principally gfCHogEntityFactory) looks at the leading characters of a layer name to find a registered "construction plan" and attach the matching C++ components. The prefix is what turns a plain layer into a piece, a cutter, a collectable, an emitter, or a piece of scene structure. Prefixes are matched literally and are case-sensitive; a name gfCHogEntityFactory cannot resolve to a plan asserts as an unknown entity type at level load.
Registered by gfCHogEntityFactory and detailed fully in the Minigame Parameter Reference; listed here for a complete prefix index.
| Prefix | Layer type | Meaning | Associated files |
|---|---|---|---|
| ROT | Rotate piece | Discrete-rotation puzzle piece; each tap advances one step | components/rotate/ |
| CUR | Rotate cutter | Cuts Rotate pieces from stencil art; also positions the minigame in place of legacy originX/originY | gfICutterComponent.cpp, components/rotate/ |
| FLP | Flipsaw piece | Swap-to-solve piece, with optional inherited rotation | components/flipsaw/ |
| FLPLGC | Flipsaw logic | gfCFlipsawMiniGameLogicComponent; tracks completion across FLP pieces | components/flipsaw/ |
| CUF | Flipsaw cutter | Cuts Flipsaw pieces; also usable to position the minigame | gfICutterComponent.cpp, components/flipsaw/ |
| SLD | Slidasquare piece | Classic or cyclic row/column sliding-puzzle tile | components/slidasquare/ |
| CUS | Slidasquare cutter | Cuts Slidasquare tiles; also usable to position the minigame | gfICutterComponent.cpp, components/slidasquare/ |
| JIG | Jigsaw piece | Draggable, optionally rotating and clustering jigsaw piece | components/jigsaw/ |
| JIGLGC | Jigsaw logic | gfCJigsawMiniGameLogicComponent; deck, drag and completion logic | components/jigsaw/ |
| CUJ | Jigsaw cutter | Cuts jigsaw pieces, including tongue/groove edges; also usable to position the minigame | gfICutterComponent.cpp, components/jigsaw/ |
| PRS | Pairs piece | Matching-pairs card; numeric suffix sets the match group | components/pairs/ |
| JTD | Join the Dots layer | Ordered-tap entity; numeric suffix sets tap order, dummy names count as complete | components/joinTheDots/ |
| DIF | Spot the Difference layer | Paired difference hotspot; naming alone drives behaviour | components/spotTheDiff/ |
| WRD | Word Search layer | Grid/tile-set word-search minigame logic; WRD-Minigame also positions it | components/wordGames/wordSearch/ |
| WTG | Word Tiles layer | Phrase-building tile layout minigame | components/wordGames/wordTiles/ |
PAR and PRC name emitter layers rather than gameplay pieces. Both are read by the fsRenderer particle components and construct their emitter from a referenced particle .txt file; see the Particle Parameter Reference for the file format.
| Prefix | Component | Associated files |
|---|---|---|
| PAR | fsCParticleEmitterComponent | particles/PAR-<name>.txt, searched in the level's localized particles folder then the global particles/ folder |
| PRC | fsCParticleCloudEmitterComponent | Same particle .txt, plus a spawn-cloud PNG from the localized level layers folder, the ordinary layers folder, then a PNG beside the particle file |
| PHT | gfCPhotographableComponent + fsCParticleEmitterComponent | Same particle .txt convention as PAR; also flagged photographable for the in-game camera minigame |
gfCMinigameWordComponent registers two further prefixes used inside a Word Search grid, distinct from the WRD layer that carries the grid logic itself.
| Prefix | Meaning |
|---|---|
| WSW | Word Search word entity — one hidden word to find. |
| WSI | Word Search image entity — a sprite paired with a WSW word (fsCSpriteComponent attached). |
All of these derive gfICollectableComponent (directly, or via gfCTappableCollectableComponent / gfCGroupCollectableComponent), so they share the same on-collection asset lookup — see Collection asset chain.
| Prefix | Meaning |
|---|---|
| PCK | Random pickable — ordinary hidden-object list item. |
| HOM | Random pickable homophone — list item shown only in English-locale builds. |
| REQ | Required pickable — must be found to complete the scene. |
| HDN | Hidden pickable — concealed list item (e.g. behind a mask or fold). |
| BNS | Bonus pickable — optional item collected into the bonus pick list. |
| BSL | Bonus silhouette pickable — "lost and found" style silhouette item. |
| BSP | Bonus photo pickable — collected via the photo-capture minigame. |
| BNB | Bonus-bonus pickable — secondary bonus round item. |
| BSS | Bonus staff pickable — bonus item counted with the staff/bonus list. |
| PCG | Group pickable — gfCGroupCollectableComponent; several sprites collected as one list entry. |
| TSK | Task — gfCTaskComponent; a rollover/task-list objective. |
| HOT | Hot collectable — gfCHotComponent; a mandated item that changes the cursor on hover. |
| TRP | Trap — gfCTrapComponent; a non-mandatory collectable, typically a hazard/decoy. |
| PRE | Lock — gfCLockComponent; collected by dragging a matching INS key onto it. |
| INV | Inventory item — gfCInventoryComponent; collected into the player's inventory with a spin-to-sack effect. |
| INT | Inventory tool — gfCInventoryComponent variant for a reusable tool rather than a consumed item. |
Identifier: INS (gfCDraggableKeyComponent). Dragged onto a matching PRE lock layer to collect it. INS does not go through gfICollectableComponent, so it has its own asset conventions instead of the chain below.
| Asset | Path convention |
|---|---|
| Inventory icon | inventoryIcons/<name>.png |
| Hit-test delegate | inventoryIcons/<name>C_hit.png (optional, refines the drag hit area) |
| Icon offset | inventoryIcons/<name>.txt (optional xOffset/yOffset key-value pair) |
| Drop sound | audio/sfx/<name>.wav |
| Prefix | Meaning | Associated files |
|---|---|---|
| ANM | Incidental animation — fsCAnimatingSpriteComponent, a looping or one-shot background animation | See Animation layer files |
| TXT | Scene text — gfCSceneTextComponent, localized on-scene text | components/gfCSceneTextComponent.cpp |
| MASK | Plain masked sprite; also the fallback for any hyphen-less layer name | components/gfCMaskComponent.cpp |
| NAV | Navigation hotspot — gfCNavigateComponent, moves the player between scenes | components/gfCNavigateComponent.cpp |
| ATR | Actor — fsCActorComponent, a scripted/animated character | components/actor/fsCActorComponent.cpp |
| TUT | Tutorial hotspot — gfCTutorialComponent, drives the tutorial sequencer | components/gfCTutorialComponent.cpp |
| parallax | Parallax layer — gfCParallaxComponent, a depth-scrolling background sprite (lower-case prefix) | components/gfCParallaxComponent.cpp |
| 3DS | 3D scene sprite — fsC3dSceneSpriteComponent (fs3d builds only) | libs/fs3d/components/fsC3dSceneSpriteComponent.cpp |
| Prefix | Meaning |
|---|---|
| Background | Sub-scene marker — gfCHogSubSceneComponent. Authored as a lower-case "background" layer name (last path segment); the loader rewrites it to this prefix before lookup. |
| GenBackground | Generated sub-scene marker — gfCGeneratedHogSubSceneComponent, used for procedurally generated sub-scenes. |
| SUB | Sub-scene navigation hotspot — gfCSubSceneNavigateComponent, moves the player between sub-scenes. |
A single-character modifier can be prepended before any other prefix on a layer name (fsCNameComponent::mHiddenPrefix / mVisiblePrefix), read by gfCVisibilityStateComponent. It is stripped before the normal prefix lookup and adds a visibility-toggle component to the entity.
| Modifier | Meaning |
|---|---|
| - | Entity starts hidden; some other trigger makes it visible. |
| + | Entity starts visible; some other trigger can hide it. |
Every layer in Collectable and pickable layers goes through the same lookup, driven by gfCCollectionEffectFactory and gfICollectableComponent, once it is collected. Each step is tried in order and the first matching file wins; more than one can fire (an SFX plays alongside a visual effect).
| Step | File looked up | Notes |
|---|---|---|
| 1. Collection animation | <sceneFolder>/<name-without-prefix>.xml, then .scml | PlayFirst XML tried first, then Spriter SCML. Must not be a looping animation. |
| 2. Collection particle | particles/PAR-<name-without-prefix>.txt | Minigame-piece collectables use the miniGameCollectionParticle app setting instead of a per-entity file. |
| 3. Default fade | none | Fallback fade-out of the entity's own sprite when no lock/hot component and no other effect fired. |
| 4. Collected SFX | <sceneFolder>/<name-without-suffix>.txt | A pointer text file whose contents are trimmed and used as the actual sound-asset path, then played. |
| 5. Post-collection particle | particles/PAR-<name-without-prefix>-post.txt | Fires once the collection effect(s) above finish; disabled again on reset. |
| 6. Post-collection marker | Global asset, not per-entity | Added only when the level table sets postCollectionVisible; the marker animation comes from the level's postCollectionVisibleMarker setting, falling back to the app-wide diffFoundMarker setting. |
Several prefixes also add a bespoke movement effect and a global (not per-entity) sound on top of the chain above:
| Prefix(es) | Extra effect | Global sound setting |
|---|---|---|
| REQ, PCK, PCG, HOM, HDN | Trail to the pick list | sfxCollectHOGList |
| BNS | Spin to the bonus trash bin | sfxCollectTrash |
| BNB | Spin to the extra-bonus bin | sfxCollectTrash (shared) |
| BSL | Trail to the "lost and found" bonus pick list | sfxCollectLostFound |
| BSP | photoCollectionParticle effect | sfxPhotoEffect |
| INV, INT | Spin to the inventory sack | sfxInventoryEffect |
| HOT | — (only if no other effect fired) | sfxHotEffect |
An ANM layer (fsCAnimatingSpriteComponent) resolves its animation data by trying four candidate filenames in order, relative to the scene folder, and using the first one that exists:
| Order | Candidate file |
|---|---|
| 1 | ANM-<name-without-prefix>.xml (PlayFirst-style animation) |
| 2 | ANM-<name-without-prefix>.scml (Spriter) |
| 3 | <full layer name with the ANM- prefix stripped>, no extension appended |
| 4 | <full layer name>, unmodified, as a last-resort literal path |
| Rule | Detail |
|---|---|
| Prefix extraction | gfCHogEntityFactory cuts the name at its first hyphen, then strips any remaining leading digits, so both ROT-piece1 and a hyphen-less ROT2 resolve to prefix ROT. |
| Case sensitivity | Prefixes are matched exactly as registered; ROT and rot are different, unregistered strings. |
| Visibility modifier | A leading - or + (see Visibility modifiers) is stripped before the prefix lookup above runs. |
| Hyphen-less fallback | Any layer name with no hyphen at all (and that isn't the parallax prefix) is treated as a MASK-type plain sprite by default. |
| background rewrite | A layer whose final path segment is literally "background" (lower case) is rewritten to the Background prefix before lookup. |
| Unresolved prefix | gfCHogEntityFactory::entityConstruct() asserts "Unknown entity type" for any prefix with no registered plan — see the AGM caveat above. |
Primary files reviewed against ~/Documents/dev/SDK/fission; update this guide whenever a registered prefix, its component, or its asset-resolution order changes:
libs/fsAppCore/src/fsCEntityFactory.cppgameModules/gfHogCore/src/gfCHogEntityFactory.cppgameModules/gfHogCore/src/gfCCollectionEffectFactory.cppgameModules/gfHogCore/components/gfCHogLevelLoaderComponent.cppgameModules/gfComponents/gfILevelLoaderComponent.cppgameModules/gfComponents/gfICollectableComponent.cppgameModules/gfComponents/components/{gfCTappableCollectableComponent,gfCGroupCollectableComponent,gfCHotComponent,gfCTrapComponent,gfCLockComponent,gfCTaskComponent,gfCDraggableKeyComponent,gfCNavigateComponent,gfCTutorialComponent,gfCPhotographableComponent,gfCVisibilityStateComponent}.cppgameModules/gfComponents/components/subScene/{gfCSubSceneComponent,gfCSubSceneNavigateComponent}.cppgameModules/gfHogCore/components/{gfCMaskComponent,gfCSceneTextComponent,gfCParallaxComponent,gfCGeneratedHogSubSceneComponent}.cppgameModules/gfGameCore/components/gfCInventoryComponent.cppgameModules/gfMinigameCore/components/wordGames/gfCMinigameWordComponent.cpplibs/fsRenderer/src/components/{fsCAnimatingSpriteComponent,fsCParticleEmitterComponent,fsCParticleCloudEmitterComponent}.cpplibs/fsAppCore/src/components/actor/fsCActorComponent.cpplibs/fsAppCore/src/components/fsCNameComponent.cpplibs/fs3d/components/fsC3dSceneSpriteComponent.cpp