Right. So let’s get down to business.
The game differentiates between the object itself (a placed chair) and so called proxies (now called “icons”… iconic things are icons right?).
The previous system therefore based on two entity definitions, let’s use an imaginary example of
stonehearth:table. The placed, usable table in the world was
stonehearth:table, the “proxy” (which is carried around and stored in stockpiles) was
stonehearth:table_proxy. That means to create any furniture (or anything that can be placed), you had to effectively create two entity definitions (two jsons, one per definition) - and they both contained about the same thing, the definition for said entity. They may had different models and small definition changes (i.e. the placed one said "I proxy to
stonehearth:table_proxy" and the proxy had "upon placement, I turn into
stonehearth:table") but they were roughly the same.
That’s redundancy and redundancy is bad. It means that whenever I change something in
stonehearth:table, I also need to adjust
stonehearth:table_proxy, or weird things happen. It’s also clustering up mods that search for entity definitions (for example spawn menu mods had to explicitly filter proxy entities). It doesn’t make a lot of sense to have two different entities that describe the same thing in the end, right?
Note for the advanced: It means that whenever an entity was actually moved, the old one was destroyed, a proxy was created, and upon placing the proxy was removed and the new entity was created. I’m not sure how/if there’s any serialization going on now that we have it or if this behaviour changed, but I somewhat doubt it - so the placed object and the original one are very likely different entities.
This all just experienced guesswork from taking a look at the files and changes, I haven’t really looked closely - but I would do it this way, which I figure is as good as any guess.
Instead of two definitions, there’s just one now,
stonehearth:table. It contains three jsons: The main entity json (which every entity has,
table.json), the “iconic” version (
table_iconic.json) and the “ghost” version (
table_ghost.json). Note that the naming can be different, see below.
The main entity definition (
The main entity definition mixins the ghost definition (
"mixins" : "file(table_ghost.json)"), which means that it takes over all settings from the ghost file. In addition, it defines a few things on its own that the ghost entity does not need, such as the
stonehearth:entity_forms component and a collision shape. It defines all components actually, since ghost entities are not allowed components (at least, not over JSON - potentially to avoid mistakes in entity definitions).
The ghost “entity definition” (
I’m not sure how real this entity definition is, seeing as it’s not defined in the manifest, yet it is used as such.
To cut to the chase, this file is about equivalent to your old
table.json. A few things can be removed, such as the collision regions (unless you want your ghosts to be solid). All components should be moved to the new
table.json however, as ghost and iconic components are not allowed to have these (unless I read this code wrong).
I would hazard a guess that this is the “placeholder” that we see in the world upon placing something down (hence “ghost”?), therefore it makes sense that name, description and all that stuff is already available.
The iconic “entity definition” (
This is really just the old proxy. It usually mixins
stonehearth:mixins:item_properties which defines most things that are required for placeable items, defines a model and that’s it.
What you described as “hiding stuff in the luac” is actually doing you a favour. Iconic entities will copy over
portrait of the “real” entity - therefore you don’t have to define all these things yourself. That means that the iconic entity definition (aka the “proxy definition”) only contains the very bare bones.
This horrible, horrible change is actually making your life easier if you let it be. Instead of updating two files (and keeping them synched) you can now use three independently. Likely, you will touch
table_icon.json once or twice,
table_ghost.json whenever the description/name changes and
table.json a lot - whenever your entity needs a change.
Note that the file names here are assuming the current naming schema, but it’s not fixed: The
stonehearth:entity_forms component (defined in the main entity definition) sets these files. You can share these, of course and you could even use four or more files (for example, use a “scaffold” json that both ghost and normal item mixin, instead of the main definition mixin the ghost one). That might not be a too uncommon case for some things - for example, you could attach a sparkly effect to your ghost items, but not the placed one, which isn’t possible otherwise with our current mixin(to) system.