# Prepared objects — v1, v2 and v3 formats

JSON format names, field names, IDs and measurements are unchanged. Photos, GLB files, arbitrary meshes, URLs, textures and scripts cannot be imported. Geometry is prepared from measured dimensions; collisions use a conservative rotated rectangular envelope.

## Version 1

An object contains exactly `format:"atelier-chambre-object"`, `version:1`, `id`, `label` and `configurations:{day,night}`. IDs are 1–64 letters/digits/dots/hyphens/underscores, starting alphanumerically. Visible labels are 1–80 characters.

Each configuration has `size:{width,depth,height}`, `appearance:{parts}` and optional `offset:{x,z}`. Width/depth range from 0.1–2000 cm and height from 0.1–1000 cm. Offset ranges from −2000 to 2000 cm per axis; omitted offset is zero.

Each of 1–64 parts contains exactly `shape:"box"`, `x`, `y`, `z`, `width`, `depth`, `height`, `color`. Coordinates locate the component centre. Local X points right, Z follows plan depth, Y points upwards; the floor is Y=0. Dimensions must be positive and colours use `#RRGGBB`. All corners must fit the size envelope. Parts cannot rotate individually in v1/v2.

## Version 2

Version 2 adds 2–8 named configurations. Each has a stable ID, `label`, `mode` (`day` or `night`), and the same size/offset/appearance fields. Both modes need at least one state. Required `defaults:{day:"state-id",night:"state-id"}` selects initial states. Optional `notes` is at most 500 characters.

Scene instances retain `choices:{day:"state-id",night:"state-id"}`. Older scenes without choices use the defaults. Changing a state changes its actual volumes and collision envelope while retaining the shared anchor, angle and elevation. Deleting and undoing preserves the object's states and placement.

## Version 3

Version 3 preserves v2 states and defaults, adding circular closed cylinders and optional component rotation. Boxes keep their v1/v2 fields and may add `rotation:{x,y,z}`. Cylinders contain exactly `shape:"cylinder"`, `x,y,z,radius,height,color`, plus optional rotation; they have no width/depth fields. Radius is 0.005–1000 cm and height 0.01–1000 cm. Their initial axis is local Y.

Rotation angles range from −36000 to 36000 degrees. Intrinsic Euler order is XYZ, matching `THREE.Euler(x,y,z,'XYZ')` after radians conversion. Rotation occurs about the component centre before the object's global rotation. Omitted rotation is zero. Unknown fields, cones and meshes are rejected. Bounds of rotated boxes/cylinders are checked before acceptance. Cylinder projections use 64 segments in 2D and 64 sectors in 3D.

Limits stay 256 KiB per object file and 64 components per state. Round tops and angled legs still use conservative rectangular object collision envelopes. Separate sample files in `objets/` are never inserted into a scene automatically.

## Placement and personal scenes

One X/Y anchor and angle are shared between Day and Night. Configuration offset places each footprint relative to that anchor in local coordinates before rotation. The object rotates around the shared anchor. No automatic recentering or conflict avoidance is applied; warnings are recalculated.

Import adds an object without moving existing objects. Duplicate IDs or names are rejected rather than silently replaced. New objects start at the room centre. The personal scene allows 50 objects. Deletion removes all states; the last deletion can be undone even after reloading. Undo that would create a duplicate is rejected.

Personal scenes use `format:"atelier-ma-chambre-scene"`, `version:1`, `envelopeId:"ma-chambre-2026-10-25"`, `mode`, `objects`, and optional `undoDeletion` (normalized to null when absent). Each object entry contains its `definition`, `placement:{x,y,angle}` and choices. X/Y are measured from corner A in cm, range ±5000; angles are clockwise on the plan, range ±36000 degrees. Physical overhangs are permitted and flagged.

`undoDeletion` is null or `{entry,index}`. Scene imports are validated before confirmation and replace only the bedroom scene. Limit: 16 MiB. Invalid data leaves the current scene intact.

Bedroom storage is `atelier-ma-chambre-v1`; the general workspace uses `atelier-chambre-v1`. No automatic migration occurs. A first previous copy may be retained under `:previous`; unknown or unreadable saves are protected and downloadable. Professional scenes use a different envelope, described in the [professional guide](../atelier-piece/GUIDE.md).

## Fixed example room

The independent bedroom envelope is 222.5 × 267 × 290 cm. Pillars project inwards from A/B/C/D. The north window and air conditioner share a 56 cm opening: sill 93 cm, lower window 77.5 cm, upper appliance 38.5 cm. Air-conditioner depth has not been measured; only its schematic front is shown. These preserved example dimensions are not measurements of your kitchen.