How to build an AssetFurnace add-on, step by step
Build a small add-on that makes crates, barrels and chests, test it in the studio, and submit it to the list. Real code you can download and change.
The short version. An add-on is a small Git repo that adds a new tool to AssetFurnace. You write one script and one file that describes it. The studio draws the buttons and forms, runs your script, and writes the licence record for you. This guide builds a real one, a crate maker, and shows every place it plugs into the app.
We built the crate kit just for this guide, so you can see each hook in a small, working add-on. Get the code, change it, and make it yours.
What you are building
Say you want crates, barrels and chests for a game, without modelling each one. The kit has three tools:
- Build a crate: pick a shape and a size, and choose whether it has metal bands.
- Fit a crate around a model: pick a model you already made and get a crate just big enough to hold it.
- Build a crate with a label: put your own picture on the front.
Each tool makes one 3D model file (a GLB). That is the whole job.
1. Make the repo
The smallest add-on is three files:
crate-addon/
addon.json describes the add-on and its tools
crate.py builds the model
README.md what it does and how to use it
That is a minimum, not a limit. A bigger add-on can have as many scripts, folders and data files as it needs, and as many tools as you like. Each tool is its own button in the studio, with its own inputs. The crate kit has three tools but only one script. A bigger kit could have ten tools and a folder of helper code.
Only addon.json has to be there. Put the repo on GitHub, public, with a licence.
2. Describe it in addon.json
This is the part the studio reads. The top of ours:
{
"schema": 1,
"id": "crate-kit",
"name": "Crate kit",
"version": "0.1.0",
"author": { "name": "AssetFurnace", "url": "https://github.com/AssetFurnace" },
"licence": "Apache-2.0",
"summary": "Crates, barrels and chests from a few numbers, or sized to fit a model you already have.",
"needs": { "assetfurnace": ">=0.6.0", "blender": ">=4.2" },
"models": [],
"tools": [ ... ]
}
needs and models are shown to people before they install. Keep them honest: if your add-on loads a model file, list its name, licence and size here, and the install screen says so.
3. Add a tool
A tool is one button in the studio. Here is the first one:
{
"id": "build",
"label": "Build a crate",
"hint": "Pick a shape and a size. Add metal bands if you want it to look tougher.",
"inputs": [
{ "id": "kind", "type": "choice", "label": "Shape", "choices": ["crate", "barrel", "chest"] },
{ "id": "width", "type": "number", "label": "Width (m)", "min": 0.2, "max": 3.0 },
{ "id": "depth", "type": "number", "label": "Depth (m)", "min": 0.2, "max": 3.0 },
{ "id": "height", "type": "number", "label": "Height (m)", "min": 0.2, "max": 3.0 },
{ "id": "bands", "type": "toggle", "label": "Metal bands" }
],
"run": ["{blender}", "-b", "-P", "crate.py", "--", "{out}", "--kind", "{kind}", "--width", "{width}",
"--depth", "{depth}", "--height", "{height}", "--bands", "{bands}"],
"makes": "glb"
}
inputsbecome the form. The studio checks them before your script runs: numbers stay insideminandmax, a choice has to be one of your choices.runis the command.{out}is the folder to write into,{blender}is wherever Blender lives on that machine, and{kind},{width}and so on are the values the person picked.makessays what comes out. Today that isglb.
The label, hint and inputs show up in the studio, in the command line and in the tools an AI agent can call. You write them once.
4. The five kinds of input
The crate kit uses all of them:
| Type | What the person sees | Where we use it |
|---|---|---|
choice | A pick list | Crate, barrel or chest |
number | A number box with limits | Width, depth, height, spare room |
toggle | A switch | Metal bands |
model | One of their own models | "Fit a crate around a model" |
picture | One of their own pictures | The label |
There is also text, for a name or a prompt.
Two things worth knowing:
- A
modelinput keeps its licence. Our "fit" tool takes a model in. The result carries that model's licence record, including any country restrictions, with no work from you. A model with no record counts as unchecked, never as clear. - Leave-it-blank inputs can't go in the command. If an input is marked
optionaland the person skips it, a{placeholder}for it inrunfails. So instead of one tool with an optional label picture, we made a separate "with a label" tool where the picture is required. Several small tools beat one tool with many maybes.
5. Write the script
The script builds the model and writes one GLB named after its output folder, <out-folder-name>.glb. Ours does three things:
- Works out the parts as plain data: how many planks, where the corner posts go, where the bands sit.
- Places them in Blender.
- Exports the file.
Keep step 1 as plain Python, with no Blender in it. We could test the crate layout in a tenth of a second, without starting Blender. Only the thin "place it and export it" part needs Blender. If you can test a thing without starting Blender, do.
Things to keep in mind:
- One file out. The studio looks for
<out-folder-name>.glb, and that is the file it records and shows. - Don't download in setup.
setupruns once at install with downloads from Hugging Face switched off. If your add-on needs a big model, declare it inmodelsso people see the size first. - Say where it runs. If your add-on sends pictures or models to a service, set
"runs": "cloud". People then see a Cloud badge and a plain warning before they install. If you leave it out, it counts as local, so that is on you. - Use
python3, notpython. The name differs between machines. - Do not write your own licence record. The studio writes
.provenance.jsonnext to your result: your add-on, its version, the exact inputs used, and any model that went in.
6. Try it before you submit
Install straight from your own repo. It shows as Unknown, because it is not on our list yet:
./lab addon add --unlisted https://github.com/you/crate-addon.git@<commit-hash>
./lab addon run crate-kit build --input kind=chest --input width=1 --input depth=0.6 --input height=0.8 --input bands=true --yes
The commit hash is the full 40 characters. Your model appears in the Library, tagged "made with Crate kit". Then try the rest in the studio's Add-ons page, as a user would.
7. What it can't do yet
So you don't build for something that isn't there:
- An add-on makes a model. It does not plug into Rig, Animate or Finish. The person carries your GLB into those steps themselves.
- It can't call the studio's own picture editor or Pixel Match.
- It returns one file per run. If your add-on does several things, make each one its own tool.
- It can't chain steps. One tool's result does not feed the next one automatically; the person picks the next tool themselves.
8. Submit it
- Go to assetfurnace.com/add-ons/submit and sign in with GitHub. You must own the repo, or be a public member of the organisation that owns it.
- Send your repo link, the full commit code, and a picture (PNG or JPG, under 600 KB).
- Checks run, then a test run on a throwaway machine. The test run tries the first five tools, and skips any that need a picture or model as input. If they pass, you are Listed, usually soon. If not, you get a plain message saying what to fix.
- Want Verified? Tick "request Verified review" on the form, and feel free to get in touch with us on Discord or X.
A new version is a new submission with the new commit code. Nothing updates by itself.
What the labels mean
- Verified: we read the code, ran it and checked its licences.
- Listed: it passed automatic checks and a test run. We have not read its code.
- Listed, not run-checked: the same, but we could not test-run it. It says so everywhere.
- Unknown: not on our list. The studio warns people every time.
Add-ons run code on a person's own machine, so be clear about what yours does.
Next
Get the crate kit, change the shapes, and submit yours. The author guide covers every field.