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?).
TĘá´ á´á´sá´
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.
TĘá´ É´á´á´Ą
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 (table.json)
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â (table_ghsot.json)
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â (table_iconic.json)
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 display_name, description, icon and 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.
Conclusion
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.
With specifics!
