Repository navigation
[FEATURE] Add temperature emitter and query APIs #237
Description
Activity
Implementation plan
Summary
Plan a small additive S1API.Temperature surface that directly wraps the native emitter, query algorithm, and formatting helpers. It must not add grid registration, persistence, networking, heatmaps, or custom gameplay effects without a separate approved contract.
Design decisions
- Keep native identity and semantics: expose direct managed wrappers for TemperatureEmitter, TemperatureEmitterInfo, TemperatureAlgorithm, and TemperatureUtility without reflection, lookup fallbacks, or reconstructed temperature math.
- Make world-position queries explicit by accepting the native algorithm inputs, including ambient temperature, origin, and managed emitter snapshots. Do not scan scenes or infer a containing property or grid.
- Treat emitters as live, mod-owned Unity components only. The first version does not register them with a native Grid, persist their configuration, synchronize changes, or create heatmap data.
Implementation
- Verify runtime seams and define the public contract — Confirm the direct wrapper path before fixing public names and unit documentation.
- Inspect Mono and generated IL2CPP temperature wrappers for component creation, struct-array conversion, delegate type, and native setter behavior. (
S1API/Temperature/TemperatureEmitter.cs,S1API/Temperature/TemperatureEmitterInfo.cs,S1API/Temperature/TemperatureAlgorithm.cs,S1API/Temperature/TemperatureUtility.cs) - Confirm the game’s temperature unit and range behavior with a targeted local runtime probe before documenting values as Celsius or Fahrenheit. (
S1API/Temperature/TemperatureEmitter.cs,S1API/Temperature/TemperatureUtility.cs) - Define factory and duplicate-component behavior for a mod-owned GameObject, preserving Unity null semantics and avoiding native-type leakage. (
S1API/Temperature/TemperatureEmitter.cs)
- Inspect Mono and generated IL2CPP temperature wrappers for component creation, struct-array conversion, delegate type, and native setter behavior. (
- Add the managed temperature API — Expose the verified native surface as documented, additive cross-runtime wrappers.
- Add a sealed emitter wrapper with temperature, range, emission position, native setter methods, and an OnChanged bridge that tracks IL2CPP delegate registrations. (
S1API/Temperature/TemperatureEmitter.cs,S1API/Internal/Utils/ManagedEventRegistrationTracker.cs) - Add a managed emitter-info value type and conversion path for the native temperature-query array. (
S1API/Temperature/TemperatureEmitterInfo.cs) - Add direct forwards for GetTemperatureAtPoint, ToFahrenheit, FormatCelsiusTemperature, FormatFahrenheitTemperature, FormatTemperatureWithAppropriateUnit, and NormalizeTemperature. (
S1API/Temperature/TemperatureAlgorithm.cs,S1API/Temperature/TemperatureUtility.cs) - Add complete XML documentation that states the verified units, live-component lifetime, and exclusions for grid registration, persistence, and networking. (
S1API/Temperature/TemperatureEmitter.cs,S1API/Temperature/TemperatureAlgorithm.cs,S1API/Temperature/TemperatureUtility.cs)
- Add a sealed emitter wrapper with temperature, range, emission position, native setter methods, and an OnChanged bridge that tracks IL2CPP delegate registrations. (
- Freeze the public contract and compatibility boundary — Cover usable syntax and prevent accidental expansion into stateful gameplay behavior.
- Add compile-only caller coverage for emitter construction or lookup, configuration, event subscription, managed snapshots, world-position queries, and formatting helpers. (
S1API.Tests/Temperature/TemperatureApiCompileFixture.cs) - Add focused managed tests only for any new validation or conversion logic; do not add reflection-only tests for direct native forwarders. (
S1API.Tests/Temperature/TemperatureContractTests.cs) - Audit changed public symbols and confirm that the additive API does not alter existing source, binary, behavioral, save, or network contracts. (
S1API/Temperature/TemperatureEmitter.cs,S1API/Temperature/TemperatureEmitterInfo.cs,S1API/Temperature/TemperatureAlgorithm.cs,S1API/Temperature/TemperatureUtility.cs)
- Add compile-only caller coverage for emitter construction or lookup, configuration, event subscription, managed snapshots, world-position queries, and formatting helpers. (
- Validate both runtime targets — Establish build evidence and leave runtime claims to a human-owned game environment.
- Restore, build, and run the S1API.Tests suite separately for MonoMelon and Il2CppMelon. (
S1API.sln,S1API/S1API.csproj,S1API.Tests/S1API.Tests.csproj) - Manually verify on each runtime that an emitter attached to a mod-owned object updates position, temperature, range, and change callbacks, and that query and formatting results match the game. (
S1API/Temperature/TemperatureEmitter.cs,S1API/Temperature/TemperatureAlgorithm.cs,S1API/Temperature/TemperatureUtility.cs) - Record that save/load and multiplayer are intentionally out of scope; require separate lifecycle, authority, replication, and restoration validation before adding native-grid registration later. (
S1API/Temperature/TemperatureEmitter.cs)
- Restore, build, and run the S1API.Tests suite separately for MonoMelon and Il2CppMelon. (
Implementation gates
- Should a later issue expose managed Grid registration so an emitter can change vanilla tile temperatures? Native Grid distinguishes gameplay and cosmetic lists, so that authority and lifecycle contract should not be inferred for this version.
- The source declarations identify Celsius-oriented helper names, but current S1API mushroom-bed documentation calls its tile result Fahrenheit. Confirm the game’s actual unit behavior before publishing unit-specific API documentation.
Evidence and validation
Evidence inspected
- Both regular Mono source trees declare the same TemperatureEmitter members: Temperature, Range, EmissionPoint, SetPosition, SetTemperature, SetRange, NotifyChanged, and OnEmitterChanged.
- Both source trees declare TemperatureAlgorithm.GetTemperatureAtPoint(float ambientTemperature, Vector3 originPoint, Vector3 point, TemperatureEmitterInfo[] emitters) and the native TemperatureUtility conversion and formatting methods.
- Native Grid owns separate gameplay and cosmetic emitter lists and exposes AddTemperatureEmitter and RemoveTemperatureEmitter. This means merely attaching an emitter does not establish automatic vanilla-grid participation.
- S1API has no Temperature namespace or wrapper. Its MushroomBedInstance only forwards the native average-tile-temperature call, while AssetRipper confirms the air-conditioner build handler enables the game's temperature display controls.
Validation performed
- Performed read-only issue, repository, Mono-source, and AssetRipper inspection. No repository files were changed, and no builds or tests were run.
Runtime validation remaining
- Run restore, build, and S1API.Tests separately for MonoMelon and Il2CppMelon after implementation.
- A human must test both game runtimes for emitted change events, component lifetime, temperature units, formatting, and query results. No Play Mode or runtime result is claimed here.
- Multiplayer, save/load, and end-to-end validation remain unperformed. They are outside this version because it introduces no replication or persistence; any future native-grid integration must validate them explicitly.
- Create a pull request to implement this plan and close this issue when merged.
Diffuin run details
- Provider:
codex - Model:
gpt-5.6-terra - Reasoning:
high(Luna advisor: complexity (high); baseline source-backed technical request) - Elapsed: 286s
- Codex thread:
01a00478-b178-7fd1-bbcb-13cfb86e834e
AI notice: Generated with AI assistance and not guaranteed accurate. Verify findings and plans against the current source and runtime.
Reacted by diffuinReacted by diffuinI couldn't complete this request.
Command failed: git push https://github.com/ifBars/S1API.git HEAD:refs/heads/diffuin/237-4b2af38a fatal: could not read Username for 'https://github.com': terminal prompts disabled- added a commit that references this issue
on Sep 9, 2026
What would you like to see?
Add a small cross-runtime API for querying temperature at a world position and configuring temperature emitters on mod-owned objects.
The initial surface could expose emitter temperature, range, position, and change events, plus the game's Celsius/Fahrenheit formatting helpers.
Why would this help?
Temperature is reusable across grid items, but mods currently need native types or patches to make custom furniture, grow containers, crafting systems, and overlays react to it.
Extra Context (Optional)
Keep the first version focused on existing native temperature behavior. Custom heatmaps, gameplay effects, persistence, and custom network payloads should remain out of scope.