[FEATURE] Fully support custom placeable furniture

[ifBars]

What would you like to see?

Add first-class support for creating fully custom placeable furniture from a mod-supplied 3D model or prefab.

S1API already provides most of the surrounding pieces: custom item registration, BuildableItemDefinitionBuilder, shops, held/stored presentation, icon generation, build events, and storage APIs. The missing piece is a public API that turns a supplied furniture model into a complete native buildable item without requiring the mod to clone and manually rewire a vanilla BuildableItem prefab.

Ideally this would follow the builder-oriented product and NPC systems. The exact API is open for design, but the modder experience could look roughly like:

var chair = FurnitureCreator.CreateBuilder()
    .WithBasicInfo("my_chair", "My Chair", "A custom chair")
    .WithModel(chairPrefab)
    .WithPlacement(FurniturePlacementMode.Grid)
    .WithFootprint(width: 1, depth: 1)
    .WithBuildSound(BuildSoundType.Wood)
    .WithPricing(75f)
    .WithGeneratedIcon()
    .Build();

The API should compose or configure the required native runtime objects for the selected placement mode, rather than exposing game internals as required builder inputs.

Why would this help?

Today, BuildableItemDefinitionBuilder can create the definition metadata, but a functional item still needs a correctly configured native BuiltItem, build handler, placement ghost, collision/footprint data, renderer culling, save/load behavior, and inventory presentation. Mods currently have to clone a suitable vanilla prefab and mutate its hierarchy and internal components, which is brittle, difficult to make cross-runtime, and easy to break as the game changes.

A supported furniture pipeline would let content mods bring their own art and produce normal purchasable, placeable furniture with a small amount of builder code. It would also centralize the fragile native wiring in S1API so compatibility fixes benefit every furniture mod.

Extra Context (Optional)

Possible scope and acceptance criteria:

• Accept a mod-provided GameObject/prefab (typically loaded from an asset bundle) as the visual source.
• Support the native placement families needed by ordinary furniture: grid, procedural-grid, and surface placement. It would be reasonable to ship these incrementally.
• Configure the placed prefab, placement ghost/preview, bounds or footprint, colliders, renderer lists, and build handler automatically, with optional advanced overrides.
• Reuse existing S1API systems for item metadata, held/stored presentation, icon generation, shop registration, and build events instead of duplicating them.
• Preserve placed furniture correctly through save/load and property reloads.
• Behave correctly in multiplayer, including authority and late-join restoration where the native building flow requires it.
• Work on both Mono and IL2CPP with the same public API.
• Keep the change additive: existing BuildableItemDefinitionBuilder and clone-based workflows must retain their current behavior.
• Include a focused example mod or documentation showing a simple non-interactive furniture item from model load through purchase, placement, save, and reload.

The initial version does not need to cover specialized interactive furniture such as beds, storage, stations, or appliances. Those could be later extensions built on the same base furniture/prefab pipeline.

[ifBars]

@Diffuin --model gpt-5.6-terra --effort xhigh -- Research and create an implementation plan for this issue.

[diffuin]

Implementation plan

Summary

Add an additive FurnitureCreator/FurnitureDefinitionBuilder that composes native BuildableItem templates from mod-owned models, initially targeting ordinary grid furniture and extending through procedural-grid and surface adapters. The native source confirms the required definition, placement, network, and persistence seams, but the serialized prefab object graph is unavailable, so prefab verification is an implementation gate before finalizing component wiring.

Design decisions

1. Expose S1API.Items.Buildable.FurnitureCreator.CreateBuilder(), returning a FurnitureDefinitionBuilder whose Build() returns the existing BuildableItemDefinition wrapper. Delegate common metadata, pricing, sound, stored-item, and icon behavior to existing S1API builders so the existing BuildableItemDefinitionBuilder and clone workflows remain unchanged.
2. Clone the supplied GameObject into an internal native template, never mutate the mod-owned prefab, and hide all native component wiring behind an internal FurniturePrefabComposer. The composer owns the BuildableItem subtype, Equippable_BuildableItem, build handler, ghost/update components, footprint objects, bounds, render/culling lists, and persistent template cache.
3. Use native BuildManager creation, native placement RPCs, and native placement save data rather than introducing a parallel furniture network or save format. Definitions and templates must be registered on every participating peer before native load; generated icons use a serialized capture queue with explicit rig reset and settled-frame synchronization.

Implementation

1. Verify the native contract and freeze the additive API — Confirm the vanilla prefab object graph before exposing assumptions, then add a runtime-agnostic builder contract.
   • Audit one vanilla generic grid furniture prefab and representative procedural-grid/surface prefabs on regular and beta, recording required component types, child paths, serialized references, network components, and renderer/collider configuration. Treat inability to construct the graph with runtime AddComponent/clone operations as a design blocker. (/data/references/s1-codearchiver-alternate/ScheduleOne-stripped/Building/BuildStart_Grid.cs, /data/references/s1-codearchiver-alternate-beta/ScheduleOne-stripped/Building/BuildStart_Grid.cs, S1API/Items/Buildable/FurnitureDefinitionBuilder.cs)
   • Add FurniturePlacementMode, FurnitureCreator, FurnitureDefinitionBuilder, and a small contract helper under S1API.Items.Buildable. Support WithBasicInfo, WithModel, WithPlacement, WithFootprint, WithBuildSound, WithPricing, explicit icon configuration, and deferred generated-icon configuration without exposing native game types. (S1API/Items/Buildable/FurniturePlacementMode.cs, S1API/Items/Buildable/FurnitureCreator.cs, S1API/Items/Buildable/FurnitureDefinitionBuilder.cs, S1API/Items/Buildable/FurnitureDefinitionBuilderContract.cs)
   • Validate missing IDs/models, non-positive footprints, undefined enum values, conflicting icon options, duplicate registration policy, omitted defaults, and builder reuse before mutating or registering a native definition. (S1API.Tests/Items/FurnitureDefinitionBuilderContractTests.cs, S1API.Tests/Items/FurnitureApiCompileFixture.cs)
   • Keep the initial public placement surface limited to verified modes; add procedural-grid and surface members only as additive extensions after their prefab graphs are confirmed. (S1API/Items/Buildable/FurniturePlacementMode.cs, S1API.Tests/Items/FurnitureApiCompatibilityTests.cs)
2. Compose ordinary grid furniture from a model — Produce a complete non-interactive grid BuildableItem template that native building can preview, place, equip, store, and manage.
   • Implement the internal composer and template registry using InactiveObjectCloner and RuntimePrefabCache. Clone the visual source, attach the verified native GridItem/PredictedSpawn/network components, create the build-handler hierarchy, and assign the native BuildableItem.BuiltItem reference before registration. (S1API/Internal/Building/FurniturePrefabComposer.cs, S1API/Internal/Building/FurnitureRuntimeRegistry.cs, S1API/Internal/Utils/RuntimePrefabCache.cs, S1API/Items/Buildable/FurnitureDefinitionBuilder.cs)
   • Generate the grid footprint and presentation configuration from managed width/depth values, including FootprintTile children, BuildPoint, MidAirCenterPoint, bounds, outline/culling renderer lists, and a default StoredItem or explicit stored-model override. Create and cache the native Equippable_BuildableItem required to enter building mode. (S1API/Internal/Building/FurniturePrefabComposer.cs, S1API/Items/Buildable/FurnitureDefinitionBuilder.cs, S1API/Items/Storable/StorableItemDefinitionBuilder.cs)
   • Implement deferred furniture icon generation through IconFactory and the shared capture arbiter, with one capture at a time, complete model/rig restoration, a settled Update/WaitForEndOfFrame boundary, visible-content validation, and shop-icon refresh after the sprite is assigned. (S1API/Internal/Building/FurnitureIconRuntime.cs, S1API/Internal/Products/ProductIconRenderRigArbiter.cs, S1API/Rendering/IconFactory.cs, S1API/Shops/ShopManager.cs)
   • Correct building event dispatch so OnGridItemCreated and OnBuildableItemInitialized also reach non-storage furniture, while preserving nullable Storage behavior and avoiding duplicate notifications during multiplayer initialization. (S1API/Internal/Patches/BuildingPatches.cs, S1API/Building/BuildEvents.cs, S1API/Building/BuildEventArgs.cs, S1API.Tests/Building/FurnitureBuildEventPolicyTests.cs)
3. Add procedural-grid and surface placement adapters — Extend the same managed contract to the remaining ordinary native placement families without leaking FishNet, Unity serialization, or game-only types.
   • Add procedural-grid composition using ProceduralGridItem, BuildStart_ProceduralGrid, BuildUpdate_ProceduralGrid, verified procedural tile type defaults, footprint matches, and rotation configuration. (S1API/Internal/Building/FurniturePrefabComposer.cs, S1API/Items/Buildable/FurniturePlacementMode.cs, S1API/Items/Buildable/FurnitureDefinitionBuilder.cs)
   • Add surface composition using SurfaceItem, BuildStart_Surface, BuildUpdate_Surface, validated surface-type options, relative placement, and managed rotation settings; reject unsupported surface configurations during Build(). (S1API/Internal/Building/FurniturePrefabComposer.cs, S1API/Items/Buildable/FurnitureSurfaceType.cs, S1API/Items/Buildable/FurnitureDefinitionBuilder.cs)
   • Use the native BuildManager CreateProceduralGridItem/CreateSurfaceItem paths internally and add only runtime-agnostic public helpers where the existing S1API Building API is genuinely missing a needed operation. (S1API/Building/BuildManager.cs, S1API/Internal/Building/FurniturePrefabComposer.cs)
   • Add contract and compatibility coverage for each mode, rotation, footprint, invalid surface/procedural inputs, and preservation of all existing BuildableItemCreator and BuildableItemDefinitionBuilder signatures. (S1API.Tests/Items/FurnitureDefinitionBuilderContractTests.cs, S1API.Tests/Items/FurnitureApiCompatibilityTests.cs, S1API.Tests/Building/FurniturePlacementPolicyTests.cs)
4. Integrate persistence, multiplayer, documentation, and release validation — Make registered furniture survive native save/load and scene reloads, document the modder workflow, and validate both build targets before runtime acceptance.
   • Retain generated definitions and native templates across scene transitions, reapply definitions before native object loaders run, make duplicate/collision handling deterministic, and fail closed with an item ID when a peer lacks the required furniture registration or model. (S1API/Internal/Items/RuntimeItemDefinitionRegistry.cs, S1API/Internal/Building/FurnitureRuntimeRegistry.cs, S1API/Lifecycle/GameLifecycle.cs, S1API/Internal/Lifecycle/SceneStateCleaner.cs)
   • Rely on native BuildableItemData/GridItemData/ProceduralGridItemData/SurfaceItemData and their loaders for GUID, item identity, grid coordinates, rotations, surface parent, and late-join restoration; add static policy tests for registration-before-load and stable IDs rather than inventing a custom save payload. (S1API.Tests/Items/FurniturePersistencePolicyTests.cs, S1API.Tests/Items/FurnitureMultiplayerPolicyTests.cs, /data/references/s1-codearchiver-alternate/ScheduleOne-stripped/Persistence/Datas/GridItemData.cs, /data/references/s1-codearchiver-alternate/ScheduleOne-stripped/Persistence/Loaders/GridItemLoader.cs)
   • Document asset-bundle model loading, the builder sample, explicit ShopManager registration, generated icons, supported placement modes, required identical mod installation on multiplayer peers, and the non-interactive scope. (S1API/docs/furniture-items.md, S1API/docs/items.md, S1API/docs/item-builder-reference.md, S1API/index.md)
   • Run the repository compatibility/build/documentation matrix and record a human validation matrix for Mono, IL2CPP, single-player, save reload, property reload, host/client placement, destruction/pickup, and late join. (S1API.sln, S1API.Tests/S1API.Tests.csproj, S1API/docfx.json, S1API.Tests/Items/FurnitureApiCompatibilityTests.cs)

Implementation gates

• Does a generic furniture template require serialized native components or prefab/network registrations that cannot be safely synthesized from a mod GameObject at runtime? This must be answered by the vanilla prefab audit before implementation.
• Should issue [FEATURE] Fully support custom placeable furniture #232 ship as a grid-first release with procedural-grid and surface modes following additively, or should all three verified adapters be delivered together?
• Should WithGeneratedIcon always queue asynchronously, or synchronously complete when the render rig is ready and queue only when it is not? The safer default is deferred generation with explicit loading-screen completion and shop refresh.

Evidence and validation

Evidence inspected

• S1API/Items/Buildable/BuildableItemDefinitionBuilder.cs:18-80 currently creates metadata and copies only the native BuiltItem reference; it has no model, placement, footprint, build-handler, or preview composition path. Its inherited build registers the definition and retains it through S1API/Items/Storable/StorableItemDefinitionBuilder.cs:448-471.
• The regular stripped source defines BuildableItemDefinition.BuiltItem at ItemFramework/BuildableItemDefinition.cs:7-18 and exposes separate BuildManager creation paths for grid, procedural-grid, and surface items at Building/BuildManager.cs:42-54.
• The native BuildableItem hierarchy requires a build handler, BuildPoint, MidAirCenterPoint, bounding collider, outline/culling collections, and placement-specific footprint or surface data; see EntityFramework/BuildableItem.cs:26-88, GridItem.cs:19-57, ProceduralGridItem.cs:22-65, and SurfaceItem.cs:18-41. Equippable_BuildableItem is the native item-equipping seam.
• Regular and alternate-beta stripped declarations match for the relevant definitions, placement classes, network initialization methods, save data, and loaders. This supports one managed design across the two Mono branches, but does not prove IL2CPP wrapper shape or runtime behavior.

Validation performed

• Read the repository AGENTS.md, CODING_STANDARDS.md, CONTRIBUTING.md, schedule-one-modding guidance, and review-issue workflow.
• Read issue [FEATURE] Fully support custom placeable furniture #232 and its available recent comments through the read-only GitHub broker.
• Inspected the existing buildable/item builders, runtime definition retention, prefab cache, building events and patches, icon pipeline, shop APIs, documentation structure, and contract-test patterns.
• Inspected the regular and beta stripped Mono source declarations for buildable definitions, placement handlers, network initialization methods, and persistence data/loaders. No repository files were modified; the worktree is clean.

Runtime validation remaining

• No dotnet restore, build, test, DocFX, or ApiCompat checks were run because this was a planning-only request; execute the MonoMelon and Il2CppMelon restore/build/test matrix before implementation delivery.
• No AssetRipper export is mounted, so serialized prefab hierarchy, object references, required network registration, and late-applied visual state remain unverified.
• No live game, Unity, Play Mode, Mono runtime, IL2CPP runtime, multiplayer, save/load, property reload, icon-capture, purchase, placement, or end-to-end checks were performed. Human validation must cover those scenarios on both runtimes.
• The native source is stripped Mono evidence only; it cannot prove IL2CPP wrapper casts, AddComponent behavior, FishNet prefab requirements, RPC generation, or Harmony patchability.

Diffuin run details

• Model: gpt-5.6-luna
• Reasoning: xhigh (source-backed issue plan)
• Elapsed: 556s
• Codex thread: 019fe4b6-6fd5-7ae0-b309-7c208da2f0f7

---

AI notice: Generated with AI assistance and not guaranteed accurate. Verify findings and plans against the current source and runtime.