Props and identity

The rules for passing props, a part’s arguments, and for identity (key), which keeps a GameObject the same object across regenerations. The list of elements and attributes is in Element reference, and how to write values is in Value grammar.

props

Props are a part’s arguments: the part declares them with <Prop> in a <Props> directly under its root element, and the caller writes values as attributes on the part tag (<Prop>’s attributes are in <Prop>).

<Hall prefab="true">
  <Plaque name="Entrance" title="Welcome"/>
  <Plaque name="Exit" title="Goodbye" offset="0 2 0" position="6 0 0"/>
</Hall>
<!-- file: Assets/Hall/Plaque.mochi.xml -->
<Plaque>
  <Props>
    <Prop name="title" type="string"/>
    <Prop name="offset" type="Vector3" default="0 1.5 0"/>
  </Props>
  <Object name="{title}" position="{offset}"/>
</Plaque>


Common host attributes	Attributes of the GameObject where the part is used; they are not props
A prop without a `default`	The caller must always pass it
How values are written	How to write a value for each prop type, and how it is converted, are in Value grammar
`Object` props	Pass an object in the same prefab to a part. The path is counted from where the part is used; inside the part, it is written in attributes that point to an object and in UnityEvent items. It can’t have a `default`, so it is always passed where the part is used. In the example below, `../Exit` is a sibling of `Bench`, and passing it on to `Seat` still counts from `Bench`

<Hall prefab="true">
  <Object name="Exit" position="0 0 3"/>
  <Bench name="Bench" target="../Exit"/>
</Hall>
<!-- file: Assets/Hall/Bench.mochi.xml -->
<Bench>
  <Props>
    <Prop name="target" type="Object"/>
  </Props>
  <Seat name="Left" target="{target}" position="-0.5 0 0"/>
  <Seat name="Right" target="{target}" position="0.5 0 0"/>
</Bench>
<!-- file: Assets/Hall/Seat.mochi.xml -->
<Seat>
  <Props>
    <Prop name="target" type="Object"/>
  </Props>
  <Object name="Cushion">
    <VRCStation stationExitPlayerLocation="{target}"/>
  </Object>
</Seat>

Syntax	Number	Example
Passing an undeclared prop	`MOCHI3005`	prop-undeclared
Not passing a prop that has no `default`	`MOCHI3008`	prop-missing
A prop with the same name as a host attribute	`MOCHI3007`	prop-reserved
Passing `1.5` to an `int` prop	`MOCHI3006`	prop-wrong-type
A second `<Props>`	`MOCHI1004`	two-props
A `default` on an `Object` prop	`MOCHI1005`	prop-object-default
An `Object` prop written in `name`	`MOCHI3006`	prop-object-as-name
A path to a missing object passed to an `Object` prop	`MOCHI2015`	prop-object-not-found

Identity and key

Identity is the sequence of markers (key or name), listed from the root, that lets regeneration treat the same GameObject as the same one.

<Gate prefab="true">
  <Object name="Pillar" key="left" position="-2 0 0"/>
  <Object name="Pillar" key="right" position="2 0 0"/>
</Gate>

<Shelf prefab="true">
  <For each="art" in="folder('../Gallery/art/')">
    <Object name="Frame"/>
  </For>
</Shelf>

<Speaker prefab="true">
  <Object name="Box">
    <AudioSource key="music" volume="0.5"/>
    <AudioSource key="voice"/>
  </Object>
</Speaker>


A GameObject’s marker	If `key` is written, its value; otherwise, `name`
Inside a `<For>`	Without `key`, the marker is `name` plus the row’s key (the GameObject’s name stays `name`). Making `key` a constant gives every row the same marker
What stays	A GameObject with the same identity keeps the same ID in the prefab across regeneration. Adding an image, inserting a GameObject, or reordering doesn’t change other GameObjects’ IDs, so references and overrides from the scene are preserved
What changes	Renaming a GameObject that has no `key`, and changing a `<For>` row’s key (the file name, for folder())
Component	Components on the same GameObject are told apart by their type and their `key`. Components without a `key` are told apart by their type and their order among the components of that type that have none. Adding a component before one of the same type without a key moves the IDs along, and the references and overrides the scene had on the first `AudioSource` move to the one added
A component’s `key`	Write a `key` when you add a component (`<AudioSource key="music"/>`), and its ID stays the same wherever others of its type are added. Giving a `key` to a component that is already there changes its ID once and moves the IDs of the components of its type without a key that come after it. Give the components of that type on that GameObject their keys together, and point to them again in the scene. Inside `<For>`, a fixed key is enough (the row is part of the GameObject’s identity)
Warning when an ID moves	When a regeneration gives the ID of a component without a key to another component of its type (one of its type was added before it, one before it was removed or moved, the one that had the ID was removed, or one of them was given a key), and a scene or prefab that places the generated prefab directly overrides that ID, points to it or removes it from its instance, a warning in the Console names that scene or prefab, the GameObject and the component type (scenes and prefabs MoCHI generates are not checked). Set the override or reference again, or restore the removed component and remove the intended one
A change that cannot be told apart	When a GameObject has, or had, more than one component of a type without a key, a component whose values changed in the regeneration cannot be told apart from one that moved. So an ID whose values changed is reported too, saying that it cannot be told which happened. Give those components keys and the warning no longer appears. With only one component of a type without a key, changing its values is not reported
An ID that no longer exists	Not reported. Unity shows a reference to that ID as Missing, and keeps an override on it as an unused override
Duplicate identity	It’s an error if two GameObjects under the same parent have the same identity

Syntax	Number	Example
Siblings with the same name and no `key`	`MOCHI4001`	same-name-siblings
A constant `key` inside a `<For>`	`MOCHI4001`	for-constant-key
A component `key` used twice on one GameObject (even on different types)	`MOCHI4001`	component-key-twice