Magic API by Carnwennann · Pull Request #3 · Nenkai/FaithFramework

Carnwennann · 2026-02-02T18:46:25Z

Core Magic API

Magic API Controller - Published Magic API as a service controller accessible by other mods
Magic Entry Reading - Uses FF16Tools.Files.Magic to retrieve complete information about properties, operations, and operation groups from the game's magic system

Magic Writer API

MagicWriter Service - New API to write/modify magic files using FF16Tool

Magic Builder Enhancements

Add Operation Groups - Added AddOperationGroup() method to dynamically add new operation groups to magic entries
Remove Operation Groups - Added RemoveOperationGroup() method to remove existing operation groups from magic entries

Magic Editor UI

Cast Magic - Added a "Cast" button on the magic editor to test the effects of magics, it lets you select the source and the target with dropdown menus.
Export to Clipboard - Added "Export to Clipboard" button to export the current magic entry configuration as JSON
MagicExporter Helper Class - New dedicated class for serializing MagicEntry to JSON format with full structure (OperationGroups → Operations → Properties)

Debugging & Configuration

Property Logging - Added configurable property logging for debugging magic API calls
Full Property Inspection - Log all properties and injections from the Game API

…itor

…for debugging.

…o log all the properties and injections from the Game API

…ation about properties, operations, operationsgroups

…tools

…ile to modify

…gic editor also now there is a MagicExporter class

Nenkai · 2026-02-03T00:05:40Z

+    /// Gets the StaticActorInfo pointer for the player (Clive).
+    /// </summary>
+    /// <returns>StaticActorInfo pointer, or nint.Zero if not available.</returns>
+    nint GetPlayerStaticActorInfo();


Don't return pointers in APIs, return specific interfaces.

Nenkai · 2026-02-03T00:06:04Z

+    /// The game's targeting system already calculates the correct position.
+    /// </summary>
+    /// <returns>A copy of the game's TargetStruct with Type=1 forced, or null if no target.</returns>
+    TargetStruct? CopyGameTargetStruct();


Same here, don't return structs. Wrap them in interfaces.

Okay will do.

Nenkai · 2026-02-03T00:07:51Z

+/// Represents a single modification to a magic spell.
+/// This is the public representation of modifications that will be applied.
+/// </summary>
+public record MagicModification


Should be an interface.

Nenkai · 2026-02-03T00:08:26Z

+/// JSON-serializable format for magic spell modifications.
+/// This structure is designed to be human-readable and easy to edit manually.
+/// </summary>
+public class MagicSpellConfig


Nenkai · 2026-02-03T00:08:44Z

+/// <summary>
+/// JSON-serializable format for a single modification.
+/// </summary>
+public class MagicModificationConfig


Nenkai · 2026-02-03T00:53:20Z

+/// This enables mods to register their modifications once and have them automatically
+/// applied whenever the game loads (or reloads) the magic files.
+/// </summary>
+public class MagicWriter : IMagicWriter, IDisposable


Why do we need a Writer?

MagicWriterAPI (I'm adding the API to it's name) modifies the .magic file in memory using your FF16Tools.Files.Magic edit functions:

Hooks into resource loading

When a .magic file loads, applies all registered MagicBuilder modifications directly to the parsed file structure

Changes happen before any magic execution

Zero runtime cost when casting spells

It's the best for permanent modifications to spell behavior.

My idea is to add here the interface to add new MagicIds, the function will the return the ID assigned:
int CreateNewMagicID(string modID, IMagicBuilder builder, string characterId, string magicFileName=Null)

MagicAPI applies modifications at execution time:

Intercepts magic casting calls

Applies modifications on-the-fly during spell execution

Has computational overhead per cast

It's the best for: dynamic modifications that change based on game state (e.g., different VFXs based on combo count, number of projectiles, casting Eid, etc.)

Why both exist:

With MagicWriter: permanent spell tweaks are "baked in" at load time.
With MagicAPI: add situational modifications are applied only when needed.

MagicBuilder is the shared component that defines what modifications to apply to a specific MagicID. Both MagicAPI and MagicWriterAPI consume it.

Nenkai · 2026-02-03T00:54:07Z

+    public static void AddScan(this IStartupScanner scans, string pattern, Action<nint> action)
+    {
+        var baseAddress = Process.GetCurrentProcess().MainModule!.BaseAddress;
+        scans!.AddMainModuleScan(pattern, result =>
+        {
+            if (!result.Found)
+                throw new Exception($"Scan unable to find pattern: {pattern}!");
+            action(result.Offset + baseAddress);
+        });
+    }


I will check how did you do the Scanning to do the same on my code.

Nenkai · 2026-02-03T00:54:31Z

+namespace FF16Framework.Services.GameApis.Magic;
+
+/// <summary>
+/// Handles magic file processing, property fuzzing, and injection logic.


It's a term used for automating injections or modification to data used by a piece of software. I will change it to terms like modification and injection.

It is frequently used in the context of finding vulnerabilities in software

Nenkai · 2026-02-03T00:56:10Z

+                    _imGui.MenuItemBoolPtr("Property Logging"u8, ""u8, ref _frameworkConfig.GameApis.MagicApi.EnablePropertyLoggingField, true);
+                    _imGui.MenuItemBoolPtr("Injection Logging"u8, ""u8, ref _frameworkConfig.GameApis.MagicApi.EnableInjectionLoggingField, true);


This needs to be made clearer, too vague otherwise

Will do, I will change them to "Log all the properties from casted Magic" and "Log all the injections/modifications done to magic from the MagicAPI"

Nenkai · 2026-02-03T01:00:30Z

I left a good amount of comments but haven't tested the behavior yet, so consider it just a code quality review for now.

My main issue with the code at the moment besides the reviews are the excessive amount of comments/docs that are pretty vague, I suspect you've used AI here and it has done a pretty poor job conveying the intent

Can you make a quick summary of how the API(s) are meant to be used? Some parts of it seems pretty overengineered and I wonder how this looks like for any consumer.

Furthermore since this is only really intended for FFXVI, service related code should probably go somewhere in Services/Faith/....

Carnwennann · 2026-02-04T22:45:35Z

I will add here how is the APIs used in tandem from the MagicAPI to the MagicWriterAPI:

// =====================================================
// Simplified example of MagicAPI + MagicWriter usage
// Based on DiaModifications.json for Diara system
// =====================================================

// 1. Create a builder to modify Dia spell (ID=214)
var builder = _magicApi.CreateSpell(magicId: 214);

// 2. (Optional) Import from JSON to avoid steps 3, 4, 5
// builder.ImportFromFile("DiaModifications.json");

// 3. Remove the linear trajectory operation
//    RemoveOperation(operationGroupId, operationId)
builder.RemoveOperation(4338, 1);  // Remove Operation_1 (LinearHomingTrajectory)

// 4. Modify existing properties
//    SetProperty(operationGroupId, operationId, propertyId, value)
builder.SetProperty(4338, 35, 35, 10.0f);  // Duration = 10 seconds

// 5. Add parabolic trajectory operation with properties
//    AddOperation(operationGroupId, operationId, propertyIds, values)
builder.AddOperation(
    operationGroupId: 4338,
    operationId: 2493,                              // ParabolaTrajectory
    propertyIds: new[] { 187, 8, 2430, 2593 },
    values: new object[] 
    { 
        2,                                          // TrajectoryType
        55.0f,                                      // Speed
        new Vector3(-90.0f, 0.0f, 0.0f),           // TrajectoryRotation
        2.0f                                        // TrajectoryCurveStrength
    }
);

// 6. Register to write changes to the .magic file
var handle = _magicWriter.Register(
    modId: "truly.eikonic.spells",
    builder: builder,
    characterId: "c1001"  // Clive
);

// 7. (Optional) Cast the modified Dia spell at runtime
_magicApi.Cast(magicId: 214);

// 8. Unregister when unloading the mod
_magicWriter.Unregister(handle);

I will add examples onto the interfaces.

Co-authored-by: Nenkai <Nenkai@users.noreply.github.com>

… the repo

… API

… added new interfaces to add and remove multiple properties at a time & improved export to JSON functionality to condense the JSON file size

…eceive a enum to choose source and target

…MagicBuilder, MagicWriter.

… the entire magicID before applying the modifications

…cture rework

… in the magic editor

Carnwennann added 9 commits February 1, 2026 04:04

Added the Magic API first iteration and also embedded in the Magic Ed…

6fb39f4

…itor

refactor: changed Magic API name and added always a property logging …

40dfb8f

…for debugging.

feat: Magic API published as a controller, made a new configuration t…

7956b78

…o log all the properties and injections from the Game API

refactor: magic API uses FF16Tools.Files.Magic to retreive the inform…

7d9cb1b

…ation about properties, operations, operationsgroups

feat: added MagicWriter API to write on the magic file using the FF16…

c15028c

…tools

fix: now the MagicWriter correctly gets a hold of the correct magic f…

7379f59

…ile to modify

feat: now MagicBuilder lets you add and remove OperationGroups

ce20b8d

feat: now an export JSON to clipboard button has been added to the ma…

2db3290

…gic editor also now there is a MagicExporter class

Merge branch 'master' into feature/magic_api

0e3b79e

Nenkai requested changes Feb 3, 2026

View reviewed changes

Carnwennann and others added 17 commits February 4, 2026 23:58

Apply suggestions from code review on the MagicEditor

3c66fa8

Co-authored-by: Nenkai <Nenkai@users.noreply.github.com>

fix: remove stray comments and dead code

8fee623

refactor: changed Magic API hooks into the Faith/Hooks as the rest of…

2e27278

… the repo

refactor: changed Actor API hooks into the Faith/Hooks

93f6a86

fix: replace the clipboard platform invocation with ImGui's clipboard…

8f590c0

… API

fix: naming conventions and clarity

f6440fc

refactor: simplify MagicModification with IDictionary for properties,…

04a39b3

… added new interfaces to add and remove multiple properties at a time & improved export to JSON functionality to condense the JSON file size

refactor: replace tuples with dedicated type in MagicWriterAPI

bfb145d

refactor: convert concrete types to interfaces

101b8c2

Removed Interface from the Actor API to avoid dealing with pointers

2a12444

refactor: move services to Faith folder

9314b38

refactor: now the cast interface from the Magic API is simplfied to r…

4f3c59d

…eceive a enum to choose source and target

chore: Updated documentation with code examples for each API: Magic, …

d43a856

…MagicBuilder, MagicWriter.

refactor: use IHostedService for initialization

87093dc

feat: added the ReplaceOriginal field for the MagicBuilder to replace…

77890a8

… the entire magicID before applying the modifications

Merge branch 'master' into feature/magic_api

0538e58

chore: removed non used and duplicated function: AddScan()

bd19fbd

Carnwennann requested a review from Nenkai February 6, 2026 19:33

Carnwennann added 3 commits February 14, 2026 02:20

fix: now Magic processor works again, after the JSON Config file stru…

5bbf499

…cture rework

feat: added a new interface to register a MagicIDs into the MagicFile

8da51d1

feat: now users can name their new modded MagicIDs to see their names…

7fb7c3a

… in the magic editor

		_imGui.MenuItemBoolPtr("Property Logging"u8, ""u8, ref _frameworkConfig.GameApis.MagicApi.EnablePropertyLoggingField, true);
		_imGui.MenuItemBoolPtr("Injection Logging"u8, ""u8, ref _frameworkConfig.GameApis.MagicApi.EnableInjectionLoggingField, true);

Conversation

Carnwennann commented Feb 2, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Nenkai commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Carnwennann commented Feb 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Nenkai commented Feb 3, 2026 •

edited

Loading