Skip to content

feat(equipmentfusion): stack non-weapon native skin-transfer stats - #17

Draft
ou3051 wants to merge 6 commits into
LocalExile:mainfrom
ou3051:feat/equipmentfusion
Draft

ou3051 wants to merge 6 commits into
LocalExile:mainfrom
ou3051:feat/equipmentfusion

Conversation

@ou3051

@ou3051 ou3051 commented Nov 10, 2026 •

Copy link
Copy Markdown

Equipment Fusion automatically adds a native skin-transfer donor's numerical attributes and independently calculated local defences on non-weapon equipment. Each target keeps one complete donor; native game actions select, bind and reclaim equipment. The GM tool only installs the mod, switches it and shows actual status.

Requires LocalExile Update: LocalExile #1155 must merge first. This supersedes the closed #790 prerequisite. The current mod uses owner-scoped GameEvents.ItemStatSources and Item.SkinTransferSource; it adds no method to IModContext. The provisional 0.5.2-beta entry is required by repository rules, not a claim that the unchanged release supports this mod. The maintainer must set the first release containing the prerequisite before merging/publication.

Behavior

  • Body armour, helmet, gloves, boots, belt, amulet and rings contribute. Both weapon hands and stored sets, including shields/quivers, are excluded.
  • Donor socketed gems, granted skills and triggered skills never enter the actor's skill-source collections. Numeric execution controls are masked only in the calculation view; B stays complete.
  • Local defences are calculated independently on A and B. Reclaim returns B intact. Disabling removes its contribution while preserving native binding/storage/reclaim.
  • Existing bindings contribute when enabled. No additional equipment-selection commands or settings. 2.0.2, author JJ ouyang, disabled by default, existing 256 × 256 icon copied to the package.
  • Cached unchanged lookups use an allocation-free loop; disposal prevents new connection-cache creation and clears retained views.

Validation

  • Mods base e873c55ac2d245e44ade722e9fe81ff3aef5c1ed; head 41cce1f9cbd099e0464c48d4bd3efb62fdb02f65. Both repositories freshly fetched; bases unchanged.
  • LocalExile base fc825ab1c658d003637943929a4fe18107956e6d; exact paired head 395b969b600abda65dee5163a3f9b53626fb3eb3. This mod cannot build against unchanged main until that prerequisite merges.
  • Release project build: zero warnings/errors. tools/build-index.ps1 -Check: current, 12 mods. Version and generated index updated; no binaries committed.
  • Actual mod verification: eight eligible rows, four excluded weapon rows, independent defences, skill/trigger exclusion, complete reclaim, enable/disable/new-instance reload and disposed-provider checks. 100,000 unchanged lookups: zero managed bytes, about 0.149 us/call.
  • Native client 3.29.3c / 3.29.3.5 hotfix, build 328126: picker/confirmation, visual binding, persistence, full stack restart, eight-slot matrix and weapon exclusion pass. On/off life 12194 / 11974, armour 474 / 63. Body +80 life and 24 + 389 = 413 armour; weapon donor +900 life contributes zero. Directly worn B exposes Fireball/Clarity, while B as donor leaves only A's Frostbolt plus Default Attack.
  • Three actual combat/reload/disable cycles free all six old private copies with no retained-mod or cleanup warning. Final status is disabled. The prerequisite collector change preserves warnings for deliberately held references.
  • Paired server Release suites: Core 443/443, Data 43/43, Gateway 638/638. Client control 40/40, GM manager 5/5, UI 12 cards.
Release condition Stat builds/s Stat-build CPU, one core Cached item-stat lookup Casts / 75 s
Unmodified main 129.86 2.00% 32.57 us 686
PR head, mod disabled 129.29 2.00% 32.14 us 686
PR head, Equipment Fusion 2.0.2 enabled 129.43 2.00% 36.29 us 686

Real 3.29.3c client (3.29.3.5 hotfix, build 328126), the same synthetic character/equipment, area 1_1_1, seed 168432811, position (290,229) and Frostbolt target (293,229). Thirty level-100 normal GravelEaters stay alive in every run; /god immune and /set_stat damage_+% -99 stabilize the workload. Each condition uses a fresh Release Gateway with Game_TRACE=lag,latency, 15 s warmup and 75 s continuous casting. The first partial 10 s logging interval is discarded, leaving 6–7 complete intervals. No module changes occur within the accepted samples.

CPU is the logger's stat-build CPU as a percentage of one core, rounded to integer percentage points; this single controlled run per condition cannot establish a sub-1-point difference. The cached lookup figure is the whole item-stat lookup, not just the mod provider. A separate 100,000-hit provider check takes about 0.149 us/call and allocates zero managed bytes. A sample disturbed by Debug's automatic module deployment was rejected and replaced with a clean Release run.

The native picker requires B's sockets empty; gem-bearing donors and reclaim were verified through native protocol packets. Shift-click reclaim and 3.29.3d were not exercised. The client remains 3.29; no game files or archive writes are included.

Additional Linux x64 Release validation on 2026-11-19 used the exact paired heads above. A real 3.29.3c client authenticated and entered an area; the GM tool queried the remote mod list, disabled/enabled Equipment Fusion 2.0.2 and reloaded it successfully. The mod ended enabled with one hook, and the server log had no retained-context or private-copy cleanup warning. This adds deployment evidence; the prerequisite remains unmerged and the review order is unchanged.

Review order

This remains draft solely for its unmerged LocalExile dependency, following the repository's Reviewing rule: review/merge #1155 first, then review this mod against the finalized API. The prior API, author, icon, version/index and live unload feedback is addressed. Maintainers set the shipping compatible version and handle releases. The author cannot add Requires LocalExile Update because GitHub denied AddLabelsToLabelable; please apply it. No approval, merge, tag or release was performed.

@Wrathen Wrathen added the Requires LocalExile Update This mod will only be compatible after a certain LocalExile PR is merged to support this mod. label Nov 10, 2026
@Wrathen

Wrathen commented Nov 10, 2026

Copy link
Copy Markdown
Member

Requires LocalExile Update: this mod needs LocalExile/LocalExile#790 to be merged first. The mod will be reviewed once that pull request is merged, and before merging the maintainer will set compatibleClientVersions to the LocalExile release that ships it.

Two questions for @ou3051, following the updated AGENTS.md:

  • Credit: author in mod.json is your name as Waypoint shows it. It is ou3051 now; is that how you want to be credited?
  • Image: would you like to add a custom icon.png for the mod (PNG, at most 1 MB and 1024 px a side; 256×256 is plenty; a game screenshot is fine)?

@ou3051

ou3051 commented Nov 10, 2026

Copy link
Copy Markdown
Author

Thanks for checking. Please credit me as JJ ouyang in Waypoint.

I have updated mod.json and the generated mods.json to use that author name, bumped the mod to 1.0.1, and added icon.png (256×256 PNG, 146,261 bytes, below 1 MB). The follow-up commit is ec63e70.

The icon shows a wand and sword joined by a magical binding, representing preserved donor equipment contributing its properties to a target item. It is AI-assisted original artwork based on the repository's in-game screenshots and the mod's feature description, rather than an extracted client asset.

equipmentfusion icon

tools/build-index.ps1 -Check passes. This update changes credits, artwork and documentation; the gameplay code is unchanged.

I understand that this PR must wait for LocalExile#790 and retain the Requires LocalExile Update label. Please set compatibleClientVersions to the shipping release during your review, as described in the updated contribution rules. The author-credit and custom-image requests are now addressed.

— JJ ouyang

@Wrathen

Wrathen commented Nov 10, 2026

Copy link
Copy Markdown
Member

The mod infrastructure has changed (LocalExile 0.4.1-beta)

Hi, and thanks for this PR. LocalExile/LocalExile#818 is merged and shipped in LocalExile v0.4.1-beta. It changes how every mod hooks into the server, so this PR no longer builds as it is. I've moved it to draft until it's updated; mark it ready for review again once it builds against main.

What changed

  • One hook system: GameEvents. Modules and mods subscribe to the same events in the Gateway (src/GameServer.Gateway/Modding/GameEvents.cs). ServerHooks is gone, and so are all the hook methods on IModContext: OnChatCommand, OnTick, OnPacket, OnAreaGenerated, OnObjectUsed, OnMonsterKilled, OnPlayerLeaving, OnHideoutReady, OnEnterMessages, OnAreaHeader, OnNpcOption, ModifyDrops, ModifyExperience, ModifyStats, UseChatServer, UseExchangeOptions and PublishExchangeRates.
  • Subscribe with your mod's id as the owner (mod.Manifest.Id). The returned handle can be ignored: when the mod unloads, the host releases everything held under its id. You no longer need lists of handles or Dispose code just to unhook. A mod's subscribers run in every league, after the league's modules.
  • IModContext keeps only the host services: Manifest, Lifetime, Folder, CharacterBuilds, Log, Settings<T>() and SaveSettings<T>().
  • Server switches are public Gateway members, held under an owner and reset on unload: ChatRoutes.Use(id, host, port), ExchangeRateStore.Use(id, options) and ExchangeRateStore.Publish(json). To have anything else released on unload, use GameEventOwners.Own(id, disposable).
  • The connection is ClientState. Event handlers get ClientState conn; Program.PlayerOf(conn) still gives an IPlayer (character, Tell, Send, …) when you want it.
  • Script mods (loose .cs files) now compile against the Gateway and GameServer.Core as well. The Gateway's types, GameEvents and Program among them, are in the global namespace. Project mods already referenced the Gateway, Core and Game through mods/Directory.Build.props.

How the old calls translate

Before Now
mod.OnChatCommand("x", usage, c => …) GameEvents.Command(mod.Manifest.Id, "x", usage, (conn, args) => …) with args a string[]; reply with conn.Commands!.Reply(text) (or Program.PlayerOf(conn).Tell(text))
mod.OnTick(p => …) GameEvents.Tick.Add(id, (conn, seconds) => …)
mod.OnPacket(opcode, p => …) GameEvents.Packet(opcode).Add(id, (conn, bytes) => …), returning true to take the message
mod.OnAreaGenerated / OnPlayerLeaving / OnHideoutReady GameEvents.AreaGenerated / PlayerLeaving ((conn, reason)) / HideoutReady
mod.OnObjectUsed(u => …) GameEvents.ObjectUse.Add(id, (conn, use, at) => …), with use.TargetId
mod.OnMonsterKilled / OnNpcOption GameEvents.MonsterKilled / NpcOption (payloads carry Conn)
mod.ModifyDrops / ModifyExperience / ModifyStats GameEvents.Drops / Experience / Stats, same payload members (Quantity, Rarity, Items, Experience, sheet.Add(stat, value))
mod.UseChatServer / UseExchangeOptions / PublishExchangeRates ChatRoutes.Use(id, …) / ExchangeRateStore.Use(id, …) / ExchangeRateStore.Publish(json)

The official mods were ported this way in #26; fastcampaign (commands, experience, stats) and itemquantity (drops) are short examples. The reference is LocalExile's Agents/docs/dev/modding.md, section "Hooks".

Before marking it ready again

  • Rebase on main, build against LocalExile main, and set compatibleClientVersions to 0.4.1-beta (or the release that ships any LocalExile change you still need).
  • Bump the mod's version, run tools/build-index.ps1, and commit mods.json.
  • Try it in game: /mod shows it loaded, and /mod_disable <id> leaves no an unloaded mod is still in memory line in the log.

For this PR

  • It calls mod.UseEquipmentAttachmentRules(…), which its companion feat: expose lifetime-owned equipment attachment rules LocalExile#790 adds to IModContext. That method can't exist any more, so #790 needs reworking first: expose the rules as a public Gateway member that takes an owner (like ChatRoutes.Use(id, …), registering its reset with GameEventOwners.Own), or as a GameEvents entry, naming no mod. Then this mod calls it with mod.Manifest.Id.
  • mod.Settings stays as it is. main.cs is a script mod, so it now also sees the Gateway's types directly.

@Wrathen Wrathen removed the Requires LocalExile Update This mod will only be compatible after a certain LocalExile PR is merged to support this mod. label Nov 10, 2026
@ou3051
ou3051 force-pushed the feat/equipmentfusion branch from ec63e70 to 026b162 Compare November 11, 2026 02:38
@ou3051 ou3051 changed the title feat(equipmentfusion): add optional skin-transfer donor stats feat(equipmentfusion): add non-weapon native skin transfer stats Nov 19, 2026
@ou3051

ou3051 commented Nov 19, 2026 •

Copy link
Copy Markdown
Author

Requires LocalExile Update: LocalExile #1155 is the current prerequisite and must merge first. It replaces the closed #790 with native skin-transfer persistence and the general owner-scoped GameEvents.ItemStatSources event.

Status rechecked on 2026-11-19: #1155 is still open and unmerged, and neither PR has new review submissions or inline comments. Equipment Fusion is 2.0.2 at 41cce1f9cbd099e0464c48d4bd3efb62fdb02f65; both upstream bases and the tested prerequisite head are unchanged. tools/build-index.ps1 -Check was repeated and passes with 12 mods.

The cloud Mod index run is action_required and needs maintainer approval to run fork code; it is not a failed index validation. The prerequisite's SQL and Tests runs need the same approval. Its Docs scan passes.

This PR remains draft under the repository's Reviewing rule until #1155 merges. After merge, the mod must be checked against the finalized main/API before being marked ready. A maintainer sets the first compatible shipping release before merging or publishing the mod.

The author account cannot add labels (AddLabelsToLabelable denied); please add Requires LocalExile Update here and protected-files on #1155. Existing implementation feedback is addressed in the linked validation response; no review, workflow approval, merge or release restriction was bypassed.

— JJ ouyang

@ou3051 ou3051 changed the title feat(equipmentfusion): add non-weapon native skin transfer stats feat(equipmentfusion): stack non-weapon native skin-transfer stats Nov 19, 2026
@ou3051

ou3051 commented Nov 19, 2026

Copy link
Copy Markdown
Author

The requested updates are complete in 41cce1f9cbd099e0464c48d4bd3efb62fdb02f65 (Equipment Fusion 2.0.2), paired with LocalExile #1155 at 395b969b600abda65dee5163a3f9b53626fb3eb3:

  • Author remains JJ ouyang; the 256 × 256 icon is included and copied by the project.
  • The old IModContext.UseEquipmentAttachmentRules API is gone. The mod subscribes to the general GameEvents.ItemStatSources event under mod.Manifest.Id; the official owner lifecycle removes the registration.
  • Current upstream bases are incorporated; version/index are regenerated. The Release mod builds cleanly against the exact prerequisite head. Unchanged main needs that prerequisite first.
  • Three actual combat → reload → disable cycles release all six old private copies, with no retained-mod or cleanup warning; /mod ends disabled. Cached-provider 100,000-call allocation is zero, and disposed providers return empty.
  • The PR body includes the real 3.29 Release fight CPU comparison and paired server's 443/443 Core, 43/43 Data, 638/638 Gateway results. Donor skills and weapon donors remain excluded.

Following the Reviewing rule, this PR stays draft until #1155 merges. Please apply Requires LocalExile Update (author label changes were denied); the maintainer selects the shipping compatibility version. The previous draft's implementation feedback is addressed, but the new API dependency must be reviewed first.

— JJ ouyang

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants