Working examples

Start with Your first weapon for complete files and step-by-step instructions. The examples below show how the API’s pieces fit together in larger mods. Their repository folders contain manifests, scripts, localization, and any required assets.

Examples under Mods/ are in the game’s loose mod directory. Older examples under ArchivedMods/ are kept outside discovery: copy the whole example folder into your installation’s Mods/ directory before enabling it. Use a test profile and follow that example’s README and verification limits. An archived source link is a reference, not a claim of a fresh game playtest.

Showcase mods

Eight player-facing mods in Mods/ show what the pieces do together. Enable them, choose Apply & Restart and play; each README lists its controls.

• Final Blow (Mods/final-blow) is a kill cam for every fight, written only with screen grades: the knockout hit pulls the camera in on the fallen fighter while time nearly stops, and critical hits and wall slams jolt it briefly. It needs no Lua at fight time. See the camera push-in. It stacks with Chiaroscuro’s knockout fade.
• Shadow Clones (Mods/shadow-clones) sells a Faceless Mask helm for one coin in the helmet shop. Its innate Lua perk shows the RaidCharge button; pressing it plays the Grasp of Darkness cast, stalls time with a script-triggered grade and raises three allied clones (independent actors with the game’s own AI) for ten seconds while the camera pulls back to frame everyone. A timed flag gates the cast and the button shows its 20-second recharge.
• Umbra, the Last Eclipse (Mods/umbra) adds a three-phase boss battle on its own map page at the Gate of Shadows. One opponent rule watches his health and caps incoming damage so no phase can be skipped: at two thirds he changes form behind a shield and a shockwave and summons two shades; at one third the arena goes dark and lightning columns hunt the player. Banners, intro and phase moments use the UI API and sf2.fx.play. Its prologue holds the fight entry with sf2.story.before_fight and plays a narrator card and portrait dialogs with sf2.story.play_sequence; a battle_result subscription queues an epilogue for the next map visit.
• Home Run (Mods/home-run) sells The Slugger, a war hammer. Its RaidCharge swing is an owned move with a physical-fall hit and a launch impulse; the perk recognises the swing in on_post_hit by event.attack.animation_name, stalls time, shows a banner and measures the flight distance from snapshots.
• The Mirror (Mods/mirror) is a fight against an opponent with your weapon type and level, chosen in the mode’s on_prepare from sf2.profile.equipment. A rule records the attacks you start; its Lua tactic echoes each one back and steps out of any attack you have used three times.
• Combo Hype (Mods/combo-hype) sells an armour whose perk listens to on_combo_changed and holds a script-triggered grade per tier (3, 5, 8 and 12 hits), refreshed by every hit, with stingers and a counter.
• The Gauntlet (Mods/gauntlet) is one fight against five opponents, one per health bar. An opponent rule caps damage at each bar, then swaps the fighter with fighter:change_form, slides the newcomer back and heals the player.
• Throw Breaks (Mods/throw-breaks) lets a grabbed fighter break the forward and through-the-back throws by pressing the throw’s own input, direction + Punch, in the first ten frames of the grab; the suplex stays unbreakable. The break is ordinary move content, so it also works in Versus: a move patch adds a named break window to each paired move, a key-pressed move selects the break, and its animation_start actions start the same push-apart on both fighters so they recover together. An every-fight rule lets the computer opponent break with a chance scaled by the snapshot’s difficulty, rolled from a saved random stream.

Their Lua runs headlessly against controlled fighters (registration, casts, spawns, form changes, lightning damage and cleanup), except Throw Breaks, which has only been checked by the editor’s static validator so far. Native rendering, the RaidCharge input, camera framing, actor AI and contact still need a playtest.

Equipment and behavior

Authored Fighter Lab ships native body geometry, a connected weighted sash, and an original generated point animation. Its owned fight offers a character chooser before entry: the prepared plan’s player_character selects the authored fighter or a core comparison character and saves that choice for the encounter. The normal Punch control selects the authored fighter’s strike. Its HUD summons an independent pair and starts the typed attack from either facing direction. The Lua source also demonstrates repeated playback, receipts, actor-local callbacks and dismissal. Use the player-form button to try the character with a character-specific Punch binding, or switch to its registered core comparison form. The comparison is not an original-loadout restore. Follow the character-authoring guide to reproduce its assets or substitute your own compatible exports. It preserves the standard point bindings and uses core idle/equipment; it is not a general rig or mesh importer. Its Left form: core / authored button changes the companion’s body through an actor reference and then its own behavior, retaining identity, private state and remaining lifetime. Read actor form changes for receipts, capabilities and the effect/projectile handover.

Example source	What to learn
One weapon	A weapon, loose sprite, core model, shop listing, and item identity migration.
A complete loadout	Armor, helm, ranged, and magic using matching core assets.
Third Strike Trial	Equipment-independent Lua battle rules with isolated round state.
Perks and enchantments	Reusable typed behavior shared by a perk and an item enchantment.

A procedural projectile burst

Scripted Burst queues three native child weapons directly from Lua. A typed definition supplies rig, equipment and flight attack; ordinary Lua computes offsets, follows receipts and guides each child. Read Live projectiles for ownership and timing. It targets Act I Tournament 3 in both modes. The full script has controlled managed Lua/HUD and editor validation; controlled Unity acceptance separately verifies three direct spawns, placement, contact damage and teardown. For independent fighters with their own health, teams and Lua behavior, see Scripted companions.

A timed arena hazard

Pulse Arena adds a moving warning column with a four-frame sprite atlas to Act I Tournament 3 in both modes. Lua updates both the marker rectangle and its capsule sensor. Yellow warning, red active and safe recovery each last two simulation seconds. Lua queries each fighter’s native collision capsules every half second of the active phase, then applies direct environmental health loss on contact. Combat pause freezes movement, atlas animation and the schedule; round/fight exit removes owned art and HUD. See Arena regions and artwork for geometry, lifetime and budget limits. This uses pose sampling and direct health changes, without solid/swept collision or the native attack/block/armor/reaction pipeline.

Camera Lab

Camera Lab adds a HUD to Act I Tournament 3 in both modes. Follow the player with zoom, animate an arena sweep from simulation frames, restore automatic native framing while keeping ownership, or release it immediately. Acquisition and movement run from on_tick; the Release button and HUD cleanup use the retained handle. Conflicts appear in the HUD. See Camera control for settings, native clamps, exclusive ownership and lifetime. This changes presentation rather than fighter positions or physics.

Larger connected mods

A framework with a gameplay add-on

Focus Framework owns a saved resource and publishes versioned services. Focus Trial depends on it, attaches a player rule to Act I tournament battle 3 in both modes, applies its third-hit bonus and displays a HUD. Enable both mods. This demonstrates separate ownership of state, shared calculations and gameplay operations. Read Framework mods and shared services for the contract. Managed Lua/combat/UI-data/save and isolated Unity font/HUD, pixel/fade and save-removal/reinstallation checks pass. Full-game contacts, menu/profile and durable save acceptance remain pending.

An objective alongside a framework

Enable Focus Framework, Focus Trial and Three-hit Objective together. Their additive rules share Act I tournament battle 3; Focus keeps its saved meter and bonus while the objective requests round wins/losses. Separate HUD placements keep both labels visible. See Combine mods for setup, ordering, conflicts, removal/reinstallation and verification limits.

Historical Definitive Edition foundation

DE128 source snapshot shows a downstream mod split into Lua modules with an explicit startup order. This package was removed from the current branch in September 2026. The description below records that historical snapshot and its verification limits; it is not a currently bundled mod or base-game authority. Consult the public API reference for today’s supported contracts before adapting its source. Its Underworld battles use audio asset handles for all 29 music IDs in the reviewed raid data. The mod ships PCM16 WAV files and resolves them by their archive IDs, so battles do not depend on the base game’s substitute music. Battle mapping checks and a native Unity loader test cover all 29 clips; audible playback in a fight has not yet been verified. Its dojo chooser adds a paintbrush button to the dojo menu, below the disciple button’s slot. It opens the game’s rolled-paper scroll with ten named dojo medallions in three columns, the shop’s scrollbar and elastic scrolling, and a gold halo around the current selection. It uses sf2.ui.dojo_button and a dojo_button story callback to select an installed core location through the saved dojo API. Ten archived choices have the required location data; two still need missing art or params. See Quests and Locations for these APIs. It makes new and saved pending forge orders eligible for instant completion and disables the six supported service groups. Its forge module also uses typed recipe and candidate APIs to split the archived Complex enchantments across three recipes and adjust the Simple recipe’s random power range. The added recipes borrow core Complex prices; the package leaves DE-only Abilities recipes for later work. It also defines Titan’s Desolator with core art, native innate perks and a name registered through Lua localization. The manifest requests policy.timers, policy.services, content.register and content.patch, plus combat.modify_outgoing_hit and combat.effects for its perk behaviors. Its story also needs story.events, story.progression, profile.read, state.read, state.write and ui.create. Content is authored in Lua without XML mod definitions. Its ChineseSwords module includes a recovered animation binary, and its Sensei story ships its own portrait and battle-preview sprites, passed to avatar and preview as sprite handles.

Saved forge deadlines are preserved until normal delivery settles the order; complete_pending = true makes it eligible without paying to skip again. Service flags suppress recognized quest groups and battle-pass source paths; complete removal of every related UI surface is not established. See Timers and service settings for the public contract and the mod’s README for its game checks. Its managed fixture executes the real Lua and checks rollback, composition and rebuilding without the mod; it does not replace a Unity playtest.

The integrated combat/offline-modes showcase also owns the forge timer. Disable that showcase before trying DE128: competing timer policies fail explicitly. Desolator has no purchase listing. DE128 now awards it through the Titan reward path using typed grant-time configuration for equipment level and enchantments. The package also installs a six-act Sensei story: battles on the existing map pages, encounters, rewards, dialogue and unlock notifications. Two of its inputs are synthesized where no source survives; the mod’s production record explains the evidence, and no full campaign playthrough has been recorded yet. The user confirmed only that a manually added Desolator worked; that does not by itself validate the reward callback’s level/enchantment settlement, save persistence, combat behavior, or runtime art rendering.

The source also includes a pending Sensei story composition example in scripts/content/sensei_story.lua. It shows how owned fight-entry continuations, saved dialogue cursors and battle-result subscriptions work together: install victory handling before unlock notifications, and use the same qualified final fight IDs for both. Portrait handles are supplied by the caller, so presentation does not depend on a particular asset namespace. The combined managed fixture checks six acts with controlled opponents and presentation hosts, including loss/retry, saved dialogue and profile isolation. This code is not loaded by the package entrypoint: verified opponent assets, perk availability, defeat dialogue and a native campaign playtest remain outstanding. It is an integration example, not a playable restored campaign.

The earlier Ascension prototype is disabled and is no longer part of the active DE restoration path. Its generic public rule and encounter-plan APIs remain documented because they are reusable modding features, but the DE package should not be treated as restoring or demonstrating Ascension at that snapshot. Its DE work had returned to XML-evidenced Definitive Edition content instead of substituting prototype progression or economy behavior.

The historical package restored the archived Master of Style and Relentless level-4 perk branch from CharacterProgress.xml, including paired upgrade choices at levels 8, 11, 14 and 17 and the five XML rank values for each perk. Their Lua behaviors follow the trigger definitions in perks.xml, not inferred aliases or name similarity. One archived contradiction is preserved: the original English Master of Style text says Aggressive or higher, while the trigger XML’s style conditions include the recovered native Brutal threshold. The implementation follows the trigger XML and leaves the English text unchanged. This archive evidence does not prove a particular DE64 or DE128 build identity.

The same XML comparison removes six obsolete direct move locks tied to the five replaced gate perks. The affected moves are DoubleJumpKick, BackFlipKick, TwoFootJumpKick, ElbowStrike, ThrowSuplex, and ThrowSuplexProfile; the two suplex moves both use PERK_SUPLEX. sf2.moves.remove_perk_lock removes only the exact direct perk lock shown absent in the archived move XML. It does not grant fake legacy perks or remove the moves’ remaining item, screen/profile, operator or inherited-template restrictions.

The shop module exposes 25 existing items from the Guardian, Skanda, Wind Maker, Time Shifter and Scriptwriter battle-pass collections at levels 15, 20, 25, 45 and 50 respectively. It uses shop availability with minimum_level, retaining canonical prices, stats, upgrade rules and item IDs. This demonstrates alternate shop access; it does not implement all archived set abilities or equipment changes. Native icon/model-text loading and controlled availability checks passed; purchases, equipment previews and save/reload still need gameplay acceptance.

The equipment module also uses combat subtype patches to restore Naginata, HunterClaws, MagariYari and Kunai routing on four existing items. Native condition/copy/rollback tests cover the mechanism. ChineseSwords is now registered through typed Lua move definitions, including its stance locks, four-hit super slash, profile title and shop preview. An isolated native fight passed move selection, attack intervals and animation completion; full hit-contact, AI and preview acceptance remains open.

The restored equipment modules add ten missing weapon definitions plus Dragon Carapace, Old Legionnaire Armour, Samurai Armour, Gabled Helm, Dragon Helm, Dragon Boomerangs, Dragon’s Breath and Lightning Arc. They demonstrate localized names, gem listings, act/level gates and default enchantments. Moon Fans uses initial_stats = {} to preserve absent initial damage. Samurai Armour uses initial_stats = { head_defense = 914 }, preserving the archive’s head-only stats instead of silently adding body defense. See the equipment API for snapshot rules. Native definition and asset checks passed. These are item-definition restorations; the shared-move module additionally demonstrates guarded native move patches for interval duration, hit reaction, sound timing and selection conditions. Native condition evaluation and patch restoration passed. Sphere1 and Sphere2 each demonstrate nine Lua-authored moves, with Minor and Medium Charge of Darkness listings. Sphere2 uses three attack edges and distinct effects, alignment and Stun restrictions. Archive comparisons and isolated native Magic-input selection, startup-to-flight transition, charge consumption and child deletion pass. Numerical damage, visible effects and shop-preview acceptance remain open. Sphere3 adds five moves and Large Charge of Darkness, including enemy-centered placement and the native Physycal reaction. Its isolated native cast, middle-phase selection, charge and cleanup also pass. ComboSphere3 adds four moves and Blast of the Void, demonstrating a bounded attack window and HighLong reaction. Its native casting, attack-phase selection, charge and deletion checks pass. MindThrowNormal adds six moves and an innate Lua perk: the cast sets an instance-owned flag, and the victim reaction or wall cleanup clears it. A native mod_expires move event selects the caster’s follow-up. Its full graph and three perk trigger traces match the historical repository XML. An isolated native fight passed contact in the normal idle stance, the owned victim reaction, one flag expiry, follow-up selection and final attack interval. The recovered projectile misses the native fixture’s crouched fists idle pose; other-stance contact and source-corpus reconciliation remain open. Remaining preview differences, purchases, equipment use and save continuity need separate acceptance work.

Visual gameplay showcases

Enable one of these examples, choose Apply & Restart, enter the map and use the bottom page dots to find its named zone. Each has its own battle; none requires replaying a particular vanilla tournament fight. Disable auto-opening menu examples if they cover the map. The menus use the original game’s fonts and UI art, and the fighters reuse native portraits and equipment.

Example source	What you should see
Pulse Guardian	A staff guardian’s shield alternates every three combat seconds. A HUD meter and stopped/landed counters track the rule: incoming damage is zero during SHIELD UP and normal during SHIELD DOWN.
Tactic Gallery	Four differently equipped opponents use patient kicks, footwork, alternating kicks and attack-window reactions. A live HUD reports the AI’s requested action or native fallback. Win to reach the next brain.
Arena Draft	A shuffled three-column opponent selector, Veteran toggle and timer slider determine the actual next fight. BACK cancels preparation; confirmed encounter plans persist through the normal save flow.

Each folder includes a step-by-step acceptance checklist. The examples award no items or currency, but save mode progress; use a test profile. The AI display reports requests, not guaranteed hits. Drafting selects from authored fighters; it does not generate new meshes or animations. Automated checks execute the exact Lua scripts and mount the UI in an isolated Unity fixture; full-game combat and physical-controller acceptance remain separate checks.

The Grid UI Showcase opens an original-style equipment selector when you enter a non-combat scene. Enable it and restart, then enter the map to test three-column layout, scrolling, selection, hidden/disabled cells and keyboard/controller navigation. It demonstrates UI layout only; its buttons do not equip items.

Branching Trial and Seeded Trial reveal their battles when a map session begins. After enabling either mod and restarting, use the bottom map-page dots to find its named zone. With several example mods enabled, another example may initially focus its own page. Each trial supplies a zones/trial localization for its map footer; registering a battle alone does not reveal it.

Each trial has three named fighters with distinct original-game portraits and equipment. Branching Trial uses Gatekeeper (kunai), Bulwark (steel batons) and Night Warden (ninja sword). Its shortcut skips Bulwark. Seeded Trial uses Wayfarer (unarmed), Needlehand (sai) and Storm Ronin (nunchaku); its seeded choice either includes or skips Needlehand. These reuse native character templates while registering separate mod-owned warriors. Existing saved route positions and seeds survive the example update.

The Charged Strike HUD shows an anchored, localized HUD, live UI updates and a click that arms behavior for a fresh combat callback. Closing the HUD cancels the armed bonus.

Example source	What to learn
Branching Trial	Choose fight routes using Lua results and saved completion counts.
Seeded Trial	Choose a shortcut using a saved random stream that resumes across profile reloads.
Generated Expedition	Generate the opponent and fight parameters after a native-styled toggle/slider preparation screen. Choices persist across reloads.
AI Dojo	Four distinct fighters demonstrate patient attacks, distance-based footwork, alternating attacks, and reactions to live attack windows using input/timing metadata.
Timed combo reserve	Combine native combo events, round state and the fight clock for a timed damage bonus.
Outgoing battle rule	Double every third unblocked hit using an attacker-side Lua callback.
Perk upgrades	Learn and upgrade a Lua guard with level-specific parameters and descriptions.
Eclipse item reward	Replace a scoped item reward on the separate Lynx Eclipse replay encounter while preserving native currency rewards.
Existing campaign rules	Append a health-dependent Lua rule and change presentation on an existing encounter.
Content and battles	Connect maps, battles, opponents, quests, equipment, forging, locations, moves, and tactics.
Combat and offline modes	Stateful behaviors, damage events, scheduled content, Ascension, and a multi-bar raid boss.
Achievements and asset replacement	Saved counters, achievements, and replacing existing assets explicitly.
Custom FX Showcase	Builds weapon-tip sparks, player kick trails, ground fog, a dojo light wash and a screen grade from sf2.fx building blocks, each with its own switch.
Chiaroscuro - Cinematic Visuals	Background depth, weapon trails, depth haze, an ink-turning rim light, light shafts with dust, a slow-motion knockout fade, film halation and grain, floor stains, and light from weapons and magic, with one Options > Mod settings switch each. Everything but depth, haze and the rim light is built from sf2.fx blocks.
Chiaroscuro 2	A showcase of nearly every visuals feature behind 30 switches: weather, fog and stage moods chosen by location, inked weapon trails with crisp edges and thrust streaks, god rays, heat haze, lightning storms, sun, moon and hit lights that shade the fighters, hit sparks and shockwaves, a slow-motion knockout kill cam, a fight that reacts through sf2.fx.on_frame, and the lacquer fight HUD. It owns the same presets as Chiaroscuro, so enable only one of the two.

These larger examples combine many features. Read one feature at a time and consult its function reference for fields and requirements. The example’s manifest tells you which capabilities and dependencies it needs.

Equipment-based achievement

Katana Achievement combines battle-result equipment with a saved counter and Profile achievement.

Repulse Trial

Repulse Trial adds a rechargeable combat HUD button that queues relative movement of both main fighters. Its click handler stores intent and on_tick acts through fresh fighter handles. See Create a movement ability for coordinates, acceptance, limits and mod composition.

Try a change

Three-hit Objective uses a HUD and round-local Lua state to require three unblocked hits in ten active simulation seconds. A declared controller requests a round win or loss through the normal score/result flow. See custom round objectives for ownership, native knockout/timeout precedence and verification limits.

1. Copy the complete example folder into the game’s Mods directory if it is not already there.
2. Enable it through the title-screen Mods menu and choose Apply & Restart.
3. Follow the example’s source README to reach its content in game.
4. Exit Eclipse, change one value, save, and launch again to compare.

For a separate mod, choose a new manifest ID and review references that explicitly include the original owner’s ID. Do not install two copies with the same ID. Keep published IDs stable once players have saved progress with your mod.

Active Strike Trial

Active Strike registers an owned punch and starts it from a Lua HUD ability. Equip fists and fight Act I Tournament stage 3 (normal or Eclipse). A transient playback receipt confirms startup before its two-second simulation cooldown begins. See Activate an authored move for explicit playback, cancellation policy and request composition. The source README records native verification and its limits.

Shifting Guardian

Mods/example.shifting-guardian demonstrates the experimental fighter:change_form workflow. Enable it, Apply & Restart, select Shifting Guardian with the map’s bottom zone dots, and fight. After three seconds the staff opponent requests a baton form. Its native-style HUD reports queued, applied or failed; queued is not proof that the body changed. Check the weapon/name, continued combat, health percentage and timer. Pause, early round ending and replay are useful lifecycle checks.

The Lua example and host fixtures are checked; full-game transformation acceptance is pending. Active stolen magic and unresolved effect references can still fail requests. This example has empty item rewards and does not replace an Act 1 fight.

Arc Dart Trial

Arc Dart adds an owned cast, launch and native flight with contact damage and miss expiry. No ranged weapon needs to be equipped. See Create a projectile ability for the complete graph and verification limits.

Actor Companions

Actor Companions adds summon, movement, damage, punch, defeat/dismiss and short lifetime controls to Act I Tournament stage 3. Additional fighters use their own health, equipment, native AI and teams. Lua stores receipts and event sequences and reacquires actor references each tick. See the independent fighter reference for limits. The core Skeleton/Standard encounter has native acceptance; arbitrary rigs, raids and multiplayer remain separate work.

Scripted Actor Sparring

Scripted Actor Sparring adds a summon/dismiss HUD to Act I Tournament stage 3. Two independent fighters share one Lua tactic while keeping separate controller memory. They approach, choose eligible punch/kick actions and wait between attacks. Copied actor IDs, owners and teams distinguish the pair from main fighters. Actual Unity acceptance includes bidirectional contact and repeated damage after later attack starts, unchanged main health, pause, fresh replacement memory and teardown. Each actor also has private reactive behavior state: outgoing damage bonuses, incoming mitigation, contact/animation observations and spawn/end callbacks. The modified damage matches native health loss, and replacement behavior state starts fresh. Core Skeleton/knife content and controlled spacing/input bound that evidence. See script companions with Lua AI.

Ranged Companion Duel

Ranged Companion Duel adds a summon/hold/dismiss HUD to Act I Tournament 3. Each independent actor creates and guides native shuriken children from its own stateful Lua behavior. Queries stay scoped to each actor and mod; contact observations identify both the child and its caster. Actor retirement cancels pending births and removes live children. See companion ranged abilities for the authoring pattern and limits.

Audio Lab

Audio Lab adds a native HUD to Act I Tournament stage 3. Play an original beacon with game or real clock, lower its volume, and stop it. The UI owns the voice, so closing it also stops playback. See the audio reference for limits and lifetime. Native source acceptance does not imply device-listening acceptance.

Text Input Lab

Enable example.text-input-lab and enter Tournament 3 in normal or Eclipse mode. Its HUD name field sends string change callbacks; its multiline modal reads the current introduction when Apply is clicked. Values remain in Lua memory. Typing captures fighter controls; combat continues. See the custom UI reference for text limits, focus behavior, and a standalone form example.