Editor Guides

[Peter]

In here I will give a short overview of how to use the editors. Be aware those editors can be a bit weird at times, there is some caveats to watch out for as they do a lot of things and sometimes the order in which you do things is important. I'll try my best to give guides for all of them so you can start creating stuff, as this all grew a bit complex over time

General Information and things to know:​

Everything you create in the exipelago editors will have some common things to it. Each Creation will have a Name and a Key. Feel free to select a name of your likings but with the key, they sometimes should reflect some sort of organization to be displayed at the correct position. Whenever you reference a different item/material, you will use the key of it (or a subsequent range of childs of a key).

The key structure will basically control where on the games UI the thing you created will be available.​

When loading all the assets, the game will actually overwrite similar keys. That way you can also provide creations for the base assets. So if you want to make a new "material" for the dirt block, you would create a material with the key "material.soil.dirt" and once it's activated in the games modding menu it will be used instead of the games own dirt material. This is true for all creations you make. So when you make your key and don't want to clash with other users naming it's a good advise to make your keys somehow unique, like using some sort of prefix to the end of it. Like instead of naming something "furniture.chair.wood" name it "furniture.chair.xyzwood". Try to avoid any special characters but underscore should be alright as well

The key of an item will also directly control it's place in the games items tree. For example, food.staple.bread will later be found in stockpiles inventory lists as
Food -> Staple -> Bread

SideInfo: The names for these parts are actually read from the localisation file, by using it's respective keys as index. You can technically supply your own localisation file with each asset you make, but as it is right now, you'd have to do this manually as there is no such function in the editors yet)

The normal way of doing things​

Open the editor from the games main menu, click on the "New" Button and the first thing you should do is actually put your key in the big input field at the top of the screen. Ideally save right away (the editor will automatically open the last edited asset).

On the Bottom of the Screen you find several tabs whch differ per editor to configure your asset.

In the upper left, you find a box for the preview Image - when you press the button, an image will be taken from your current view.

The view is currently always centered at the asset you create (may change in the future) otherwise the controls are the same as in the game itself

The other Buttons on the top of the screen are for exiting to the main menu, loading an asset you created, saving the asset and sharing the asset (which is basically publishing it on the workshop)

Publishing on the workshop​

If you want to publish your item on the steam workshop and make it available for others to use, click the share button (make sure you have made a preview image by clicking the camera button on the preview image box). Make sure your item is already saved and you already gave a name & proper key to it. Set visibility to your likings and click "create".
The same procedure is used when you want to update the item on the workshop: Open an existing item, do your changes, click share and so on

General adive: If something does not work out .. restart the game and open the editor again. There is some quirks here and then which needs the game to reload the assets first to work properly

 

[Peter]

Tree Editor​

Maybe one of the least complex editors right now. The Tree Editor lets you create your own trees with everything around it. Trees are procedurally created in the game and in this editor you define all the paramters for a specific tree type. Let's go over the tabs and briefly discuss what's in there:

Properties Tab​

This is mainly for all the optical things to the tree. How tall will the tree grow, how much noise is used .. maybe just play around with the controls to see what they do.

"Grows on": this will preset on which sort of material those trees can grow. There is currently only "gras" (works on dirt as well) and "sand" in there

Textures Tab​

Ok, here are the fleshy bits. A tree provides 4 textures

Leafs (Color): The basic texture of each leaf (branch). You can import whatever you want here, just make sure it has proper alpha channel (the stock trees use textures of 1024x1024). As of right now, it has to be square

Leafs (Normal): The Normal Map four the Leafs Texture. This is to give some detail to the actual rendering. Always provide one.

Bark: Here is where things get interesting. The Bark can be created by using the ingame Texture Editor as it will rely on the internal material system. The bark is what will be used for texturing the actual tree stem and subsequent logs, when the tree is chopped down.

Wood: This serves 2 purposes. For one, the game will use it together with an internal overlay to create the flat sides on a log but more importantly, it will be used as a base layer for everything created out of logs, like planks. Think of it as the plank texture, as a plank made out of your new tree will basically have that pattern applied to itself and every item made out of this plank

Top Right Controls​

Here you can move the slider to show different age phases of your tree or create a new seed for visual inspection, so you can see how different iterations of your tree would look like in the game

 

[Peter]

Plant Editor​

The Plant Editor is pretty similar to the tree editor, but there is some things to consider. First of the key, you give to your plant may influence how your plant is recognized in the game and should always start with "plant." prefix followed by the subtype and followed by your own name. An example is "plant.crop.what", so it defines to be a "plant", especially being a "crop" and finally defining, which crop by putting the addition "wheat". So if you wanna make barley, you would name it "plant.crop.barley", if you wanna do some bush, you would call it "plant.bush.myfancybush" or something

Properties Tab​

As like with trees, plants work procedurally in the game, so you define some basic parameters for it. It's best to just play around with the controls to see what they do.

Tint1 / Tint2: This is used to give a color overlay for the grow state (tint1) and the ripe state (tint2) - this is currently used for wheat, as it will be green while growing and finally ending up yellow once its ripe and ready for harvest. Ingame these colors will experience a transition from on to the other. Be aware, that this is a tint, so ideally your texture is grayscale)

Grow Time: The time in Game Hours this plant needs to fully grow

Fruit Time: The (additional) time the plant needs to be ready for harvest. Can be zero when there is no additional fruit time. Especially important for plants with regrowing fruits (like berrie bushes)

Texture​

All textures in here use the internal material system and therefore support the internal material editor.

Plant Texture: The basic texture for the plant, this is how the plant will look like,

Grain Texture: Ok, so this is used for plants which actually produce something once harvested. This texture will define how the material will be. Currently most items will put the harvest into a basket and this texture will be used to display the content of that basket (more info about that in the part about the item editor)

Ripe Texture: This texture will slowly fade in during the "Fruit Time". For example a flower will have only green leaves in its base texture, but also just a flower in the ripe texture. The berrie bush has the texture overlay for berries in here. Wheat does not use this texture

Attributes​

Can Harvest: Either this plant can be harvested (using the harvest tool) or not

Destroy on Harvest: If this plant is destroyed on harvest. For example wheat will get destroyed (and has to be replanted) while a berrie bush will just keep there but will get reseted to its respective state and the Fruit Time begins from zero

Yield Harvest: Amount and type of item which will be created after harvesting. Make sure to provide this item as its own workshop download and interlink it there manually, so other players don't miss any assets (yes, currently this has to be done manually in steam). Enter the key of the item which will be created

Yield Cut: Same as above but when the plant is cutted down instead of harvested.

 

[Peter]

Item Editor​

That's the most complex one, so take a seat, relax and let me try to guide you tru. The key you choose for your item will have some influence about where it will be found in the games item menu later on, so find something you find appropriate .. if you do some furniture, start with "furniture." if you do some item as a harvest result do something similar. Like "Berries" use "food.berry" (recommended food prefix for consumables) or "material." for material items like logs, soil etc

Properties Tab

Dimensions: How many tiles will this item use up in either dimensions and would it need to be placed next to walls (torches) or floor is enough

Stack as: Stacking Mode (there is different types of stacking, whic is when several of the same item are on the same tile)

Stack Max: How many of these can be stored on the same tile and therefore stack

"can walk over": Can villagers walk over this item. May be true for materials, but unchecked for items like an oven

Tool Type: If this item will be used as a tool, set the type of the tool (predefined list of tool types for now). Is it a workbench? An Oven? Or no tool at all (furniture)

Use Displace: This is used to define an Offset for items INSIDE this item. For example, a bread wil be displayed inside the opening of an oven and so own - the editor will show a small cube to better find a good position

Meshes:​

This is where the fun begins. This defines the actual geometry of your item. Use a 3D Editor of your choise and create the geometry of everything. Make proper UV and imagine the UV being a 64x64 texture reassembling the material which will be applied by the game. For example a wood table made out of planks will get the texture of the used plank. It's your job in the editor to make proper UV Coordinates. If your item has several Materials used, make sure to give the 3D object also different materials to reassemble those differences. Export as OBJ (triangulated!).
In the ditor, click "Add" open the respective OBJ File and select the meshes to import (this should give entries for each material you defined in your 3D Editor). The Exi Editor will no import the meshes into its own format. You can now select each imported object in the list of "Imported Meshes".

Now you can apply several transofrms to it, like scale, position or rotate it by increments of 90° (you can use the mousewheel when hovering over a field for small increments)

Next to this block you will find the Map Materials Box, this will now show the materials you applied to this mesh. Each material will be linked to an internal game material later on, you just need to give proper information about it. I tend to already name these materials correctly in the 3D Editor (I am using blender), so I can see what to use after importing.

Selecting one of these will bring up the internal mapping screen. Here you basically define which internal material will be used to texture this mesh/submesh. Each material (imagine a cube/voxel) will have a top and a side texture. For example a log will have a top and a side texture, where the side texture is the bark and the top texture the inside with rings. Most likely you want the side texture

Source: This defines what the source will be. Per default this is set to Item, which means it will take the texture from the item it was crafted with. So a table made from a birch plank wil have the birch texture on it.

You can also set this to material to forcefully apply a defined material (the food.berry item uses system.basket here for the basket material). Be aware, that this material has to be known to the game, either by being a system material (there is only system.basket rn) or a material you supply via workshop on your own and bundle it manually (via workshop).

The other option is Texture, which will give you the option to supply a distinct texture with your item which will be used - use this carefully, and dont use more than 1 per item for now, it's pretty untested

Ok, so when you do all this things, you may encounter the editor is not rendering anything. The main reason for this is, because it doesn't know how, when the item depends on other items. To fix this we have to jump forward to the

Important things to know​

For your item to work properly, you have to consider several things. Each part of the mesh will use a specific source, the possible sources are:

"item": this means, the mesh part will be textured by the item which was used to craft it (ingredient from construct tab) - this means that the ingredient has to be configured in the construct tab and you are obligated to use a CATEGORY and not a specific item for it. So if it needs a log, you specify "material.log" - you do not specify "material.log.pine". For every mesh part configured as "item" there has to be a subsequent "ingredient" with a matching output in the construct tab.
(you can have ingredients without a mapping in the mesh tho)

"material": this means, the mesh part will use a specific material for itself. This has no relation to any ingredient, it will use a specific material which must be none to the game. So if you want this part to have the texture of a pine log you have to specify "material.log.pine" - you can not specify a category like "material.log"

"texture": this means the item will supply its own texture for this part of the mesh. When selected, a new window will appear which allows you to paint that texture. Internally - upon loading of the item - the game will create a material with the same key as the item. Therefore you can only have ONE self-supplied texture per asset

If you fail to meet this requirements the outcome in the game is undefined

Construct Tab​

ok so in here, you first define if this item is constructable. Furniture is constructable. Grain is not. Check this if your item is going to be crafted leave it unchecked if your item is supposed to spawn on its own.

"In Zone": If being crafted, define here, which zone will be responsible for crafting it. Leave empty if the item is going to be crafted "in place" (true for items which are not supposed to be carried but only assembled on a specific place, like an oven)

"Needs Tool": Which tools is needed to craft this item? What this means is, that in order to make a plank, you need a sawbuck. So a plank will define "sawbuck" here, a bread will define oven here and so on.

Yield/Time: How many of this will be created when crafted? And how many (game seconds) will it need to be fully crafted

So now we come to the bit why we jumped over here in the first place, the Ingredients.

Here you need to define what ingredients are needed in order to build/craft this item. Let's take a table for example, it will need planks. Any Plank. Not a specific plank, so we click "Add" and select "material.wood.plank". So now the game finally knows how to render everything and in the top right, you should be able to switch different subtypes of plank to see how it will look (if this doesnt work right away, save your item and restart the game/editor so it can reload assets)

When selecting an ingredient, you can also define several other things, let's go over them:

"Input": This is the item group which is needed to construct this item. Be aware you cannot define a specific item but an item group. Like "plank" but not "plank.birch"

"Output": This is the MATERIAL used to texture your item. So the plank ITEM is different than the plank MATERIAL, but they are named the same. In most cases you will have Input equal Output. A special case for example would be planks, as planks have a log as inputm but will use the plank material. The game will just use the output and append the local key part from the input to it. So a log.pine will get translated to plank.pine for texturing purposes

Actions​

Ok, what is actions. Actions is, when a villager "operates" an item. Like an oven has exactly one action, which is the villager standing in front of it. Here you can basically define several actions for an item to be "operated". Each action defines a "spot" for 1 villager. So while an oven has only 1 Action toit as it can only be operated by 1 villager, a table may have 4 actions, 1 for each side.

Each action has a forced pose to it (only used by beds right now to make the sleep pose) and you can move the spot around. The Tile X/Z defines the center point of the ACTION, not of the villager when doing it, for that see the followeing

Each Ation also has1 or more locations to it. A Location is basically the spot for the villager to be on when doing an ACTION. So for an oven, the ACTION itself is directly on the OVEN while the location is the tile in front of the oven. You can have several locations, locations are also the points where the villager will go - if no location is reachable in the game, the item becomes inoperable.

Effects​

Here you can add several Effects. Currently there is only fire, which is used by the campfire and torches. It's not very complex and self explanatory. It may happen that your editor is in pause mode, so if nothinghappens, press SapceBar to see if that's the case.

SubTypes​

ignore that for now - it's fully untested and may not work as expected

Attributes​

Each item can have several attributes tied to it. Like consumables will have nutrition, each item may have several values or value multiplier. Many of them are not used yet (except nutrition). For example a nutrition value of 100% would basically mean a full stomach

 

[Peter]

Material Editor​

Materials are basically the backbone of the games textureing system. But it's easiest to think about materials being the blocktypes, because that's basically what this editor is mostly used. Here you can define new types of walls or blocks (not the shape, just the surface)

Be aware, that naming for the materials key will have impacts on how they are used in the game. If you create a material.soil.clay - it will be handled as a soil subtype - but you can also define category types like a Stone Wall.

Properties​

"Blockable": Check this if your material can be used on a block, this also means the player can build blocks with this material once the material is discovered. An example is a Stone Wall.

"Needs": This is the item needed to build this block. For a Stone Wall this would be material.stone.raw (the game will use the subtypes of stone.raw and create the subtypes of the blockwall on its own). If you define a specific material here, no subtypes will be created and it's handled as distinct item.

If you define a base material - like for example material.soil.clay - you have to set the need to the material itself. For this to work you have to first create your item, save it and restart the game/editor in order to have it available to select)

Examples:

material.soil.clay will need material.soil.clay (both distinct types)
material.stone.blockwall will need material.stone.block (will create a blockwall for every type of stone.block)

Texture​

Here we again use the ingame texture editor (btw you can import images as well, as long as they are 64x64). The Main Texture is needed and the top texture is optional (if your block looks different on the top)

There is several parts in the Texture Editor to know. First of there is the 3 major parts like the color map, the high map and the normal map. The latter two can be autogenerated while you paint - if you dont want that to happen, turn it off at the bottom of the window. The same is true for automatic noise during painting.

While the game uses 64x64 textures, the ingame texture editor will only give you control over a sparse 16x16 Grid. If you want finer control, you have to use a 3rd party software to make your images and import them using the ingame editor.

Alpha​

Alpha is "different" .. you can set the alpha channel in the color selector to make Alpha Values in the Color Map. This is used for plants. The Alpha Map has a different use - it is used for overlaying, to understand that better, lets make an example:

You want to make a block wall, which will be made out of an unkown type of stone blocks. So what you do is, you paint your blockwall in grayscale and use the Alpha Map to define which parts of your own texture will be opaque and which parts will be blended with the actual texture of the material used to create it. So in the Alpha Map, every white pixel will not be overlaid/replaced, while every black pixel will be replaced by the texture of the material used.

That way you can make blocks, which will reassemble the material they were made out of. A serpentine Block Wall will look like serpentine, while a SandStone Block Wall will look like SandStone. And if someone invents a totally new type of stone, it will work with your Block Wall as well.

Attriutes​

see Item Editor, it's basically the same here

 

[Peter]

Localisation & Labels​

While switching languages is not yet implemented, if you want to supply additional labels to the game together with your items, you can do so by manually adding a labels file for it. To do so just create "labels.txt" into the folder of your item (you can find them in <exipelago>/assets followed by a directory with th UID of your asset, which can be found, when clicking the share button).

The format of this file is basically like a regular .ini File and may look like this, if you want for example to give a name for a category which does not yet exist in the game. So if you make an item in the category furniture.decoration, your labels.txt would look like this:

[EN] furniture.decoration = Decoration

The game will load this file together with the asset and adds the said Labels to its database for displaying them in the games building UI

 

[Peter]

OBJ File restrictions:​

When importing your own meshes make sure it follows the following restrictions:

• must be triangulated
• must define UV coordinates (where the texture will be the material mapped in the editor, which is a 64x64 texture)
• must define different materials for each differently textured part (obviously)

you can define vertex colors.

It's best to have highly optimized meshes (low poly), do not make high detailed models, as this may overwhelm the game engine pretty quickly