One new word. One new thing you can see. Then stop and play with it.
Brand new computer? Go back one tab to 0 ยท Set up the computer and do those seven things first. If that's already done, you're in exactly the right place.
A computer is very obedient and very forgetful.
It does exactly what you tell it. And it knows nothing until you tell it.
A mod is a list of orders you write down. When the game wakes up, it reads your list from top to bottom and does what it says. Anything you never told it about? It never happened. Not hidden. Not locked. Just never heard of.
That's the whole trick. Every level here is just giving more orders.
| Word | Kid words | What it really is |
|---|---|---|
register | Tell the computer a NEW THING exists | Adding a definition to the game's lists |
node | A block you can put in the world | A block type (dirt, glass, rainbow) |
print | Make the computer say something we can see | Writing a line to the log |
Why each level has one new word If four things are new at once, nothing sticks. One thing, seen working, remembered.
Every time you change anything, you do the same four beats. All day. Every level.
./deploy.sh -r magicThe rule Nothing in the game changes until the server wakes up again. There is no "save and it appears". Restart IS the reload. This feels slow for ten minutes, then it becomes the most normal thing in the world.
These two rules break more blocks than everything else combined.
magic: โ that's your family. Nobody else's block can
ever bump into yours.magic_ and matches the code exactly.
Same letters, same underscore โ or you get the purple "I don't know" block.Nothing can be lost. The folder mods/magic in the repo is always the truth.
A grown-up puts that folder back the way it wasGrown-up runs ./deploy.sh -r magic and the repo copy goes back into the game โ and the
copy that was in the game got saved in .backups/ first, automatically.
A rule we keep Never stop for the day with it broken. Go back to the last thing that worked. A mod that was reverted still taught you something. A broken mod at bedtime teaches you to hate this.
Before we make a single block, we get the computer ready. Seven things. Each one has a reason, and each one has one small job that is yours โ so you always know what changed.
Why we do this When all our things live in one place, the computer always knows where to look, and so do you. Scattered files are the number one reason a lesson gets stuck and nobody knows why.
luanti. Everything we ever make goes
inside it. Nothing goes in your Downloads folder โ that place is a swamp.mkdir -p ~/luanti~/luantiC:\luanti beats a synced Documents folderWhy we do this
git takes a photograph of every file every time you tell it to.
Those photographs are saved forever. Break something badly on purpose or by accident? You go back
to any photograph you ever took. It is the best undo button that exists, and it works even if you
deleted the file.
git (every OS has a package for it), then tell it who you are so every
photograph has a name on it:
git config --global user.name "your-name"
git config --global user.email "you@example.com"
Then get the lessons: git clone <this repo> ~/luanti/tutorial.
Do one commit together โ git status, then
git add, then git commit -m "..." โ and let the child press Enter.
Ten seconds, and the word stops being scary forever.Why we do this Every block you will ever make needs a skin. Pixelorama is where you draw that skin. The game uses tiny pictures โ 16 ร 16 dots โ and a tiny picture drawn by you looks better than a huge one drawn by nobody.
<modname>_<thing>.png โ e.g.
magic_rainbow.png. The prefix is not decoration.mods/<mod>/textures/, and the name in the code and
the name on disk must match character for character.Why we do this A code editor paints the different kinds of word in different colours. That colour is how you see a missing quote or a bracket that never closed before the game has to complain about it. Word processors do the opposite โ they hide and "fix" characters, which breaks code silently.
mods/magic/init.lua. Point at a word and tell me what colour it is. That colour is
information.nano/vim if that is your preference. Anything that opens plain text and
colours Lua works. Whatever you pick, make it the thing the child sees you use โ and pin the
mods/ folder so the file tree is always visible.Why we do this You cannot learn to mod a game you cannot open. You need the game running and your own world to break in.
~/.var).Why we do this The terminal is a place where you tell the computer things by typing whole sentences instead of clicking. Every "get it into the game" step happens here. It looks intimidating for about four minutes and then it is the normal place you live.
pwd and press Enter โ that means "where am I?"
Then type cd luanti and press Enter, and type pwd again. See how the
answer changed? That is all the terminal is: you ask, it answers.Why we do this We check now, on purpose, so that later a broken computer never looks like a broken you. If the tools are proven good at the start, then when something fails in Level 3 we know it is the code โ and code can be fixed.
./deploy.sh --detect โ the script can find the game container and the
world path. Proves the pipe exists../deploy.sh -l โ it can list the mods in the world. Proves you can
actually reach it, not just see it../scripts/lint-lua.py mods/*/init.lua โ every mod file is
well-formed. Proves the code can be read. (There is no Lua installed anywhere here, so this
is the best available check offline.)./scripts/check-lesson-code.sh โ the page and the lessons say
exactly what the game is running. Proves the tutorial is not lying to the
child.ssh deploy@<server> docker ps โ the
deploy key works. Setup for that is
docs/deploy-user.md and it is your job,
not the child's โ see the honesty section in that file about what a docker-group user
really is.What you are actually teaching: register. Not syntax โ the
idea that the game keeps lists, and a mod adds to those lists.
If he gets that one thing, Level 1 has done its job. Everything else on the page exists to make
that idea land.
If he can say that, stop. Do not push further today. Depth comes from repeating the same idea at the next level, not from cramming the next idea into this one.
./deploy.sh -r magic and read the log.
You are looking for [magic] My magic mod is awake! If that line is not there,
nothing else in this session matters โ fix that before you hand him anything../scripts/check-lesson-code.sh must say PASS. If it does not, he would be reading
a description of something that is not running, and every confusion that follows is our fault,
not his.magic_rainbow.png as a stand-in. Open Pixelorama with a 16ร16 canvas ready, or
have his own drawing already dropped in. Level 1 is much better if the picture is his../deploy.sh -r magic puts the repo copy back, and the copy that was in the game is
saved in .backups/ automatically. Say this out loud to yourself before you start.
It changes how calm you are at 8pm.[magic] My magic mod is awake! and no
ModRunError.light_source = 14.tiles and the file in
textures/. Read them side by side with him; do not fix it silently.world.mt, the map files, or anyone's inventory. Deleting our own
single mod folder is the rollback. Everything else is out of bounds../deploy.sh -r magic ships to the dev world. That is the only
target this page ever asks you for, and it should stay that way.
Promotion to the live server is a separate, deliberate act by you, from your own machine, with your own credentials. It is never a step in a lesson, the child's computer does not hold the key to it, and nothing on this site will ever ask him to do it. That rule is in docs/deploy-user.md and it is not optional.
Read two things on this page before he starts: the "Your whole file" block at the bottom, and the "If it broke" table. Those two are what you will be asked about, and knowing them means you can answer in one sentence instead of four.
You are making a brand new block that has never existed in this game before. You make it, you name it, you draw it, you put it in your world.
When you're finished: a block in your inventory called Magic Rainbow Block that you can place anywhere โ and it glows in the dark.
register โ tell the computer a new thing exists, and give it a name.Our file is called init.lua. init means start. The game
reads this file before any other file in the mod.
-- My magic mod. The game reads this file when it wakes up.
print("[magic] My magic mod is awake!")
The first line starts with --. That means this line is for humans.
The computer skips it. Those are called comments.
./deploy.sh -r magic[magic] My magic mod is awake![magic] is our name tag
so we can hear ourselves in there.Before you register it, the block does not exist. Not hidden behind a door โ nobody has ever mentioned it to the computer. After you register it, it is real.
Here is the rest of the file. This is the part that makes the block exist:
core.register_node("magic:rainbow", {
description = "Magic Rainbow Block",
tiles = {"magic_rainbow.png"},
light_source = 14,
})
core.register_node( โ "Computer, MAKE A NEW BLOCK.""magic:rainbow", โ "Its real name is magic colon rainbow."description = "Magic Rainbow Block", โ "The name people read is Magic Rainbow Block."tiles = {"magic_rainbow.png"}, โ "Its skin is the picture magic_rainbow.png."}) โ "That is all the things. Go."There is one more line in the real file โ light_source = 14 โ and it is a number we
come back to in step 5. Don't touch it yet.
magic: is our family โ every block we make lives here, so nobody else's block can ever
bump into ours. rainbow is this block's own name.To the computer, magic:rainbow and magic :rainbow and
magic:Rainbow are three different names. Spaces and capital letters
count. The computer never guesses what you meant.
file on the disk: textures/magic_rainbow.png
code says: tiles = {"magic_rainbow.png"}
Same letters. Same underscore. If they do not match, you get the purple "I don't know what this is" block. That purple block is not an error โ it is the game pointing at this exact line and asking "which picture did you mean?"
./deploy.sh -r magicChange one line. Only the words inside the quotes:
description = "Jonathan's Super Rainbow",
./deploy.sh -r magic๐ Your block has a new name in the game. Now the important part. You changed
the label. Its real name is still magic:rainbow โ and you
never change that one.
description = what humans read. Free to change.
magic:rainbow = what the computer remembers. Do not change.
This is the best part.
1. On your own computer, open Pixelorama โ New image
2. Width 16, height 16. Not 100. 16. That is one block's skin.
3. Draw. Fill every single dot โ no empty squares, or your block has holes you can see straight through.
4. Export as PNG, and name the file exactly magic_rainbow.png
5. ๐ง copy it into mods/magic/textures/ on the server โ say yes, replace
6. ๐ง a grown-up puts it into the game./deploy.sh -r magic
7. ๐ง go look in the game.
That is your drawing, as a solid thing you can stand on.
Keep your Pixelorama project file. You can always go back, change it, and export again.
One number to play with. It is already in your file โ the last line inside the
{ }:
light_source = 14,
Your whole file right now:
-- My magic mod. The game reads this file when it wakes up.
print("[magic] My magic mod is awake!")
core.register_node("magic:rainbow", {
description = "Magic Rainbow Block",
tiles = {"magic_rainbow.png"},
light_source = 14,
})
If you changed the description back in step 3, yours has your words in that line
instead. That is allowed โ the label is free.
1. Deploy. Look. Then 5. Then 15. Then dig
your block away and place it again at night.Nothing bad happened. The game told you exactly where it got lost. Fix that one line. Loop again.
| What you see | The game is asking | What to do |
|---|---|---|
ModRunError + a line number | "I got lost on line N โ did you close everything?" | Look at that line. Count quotes and brackets. |
expected ')' near '}' | "A bracket is still open from earlier" | Find the ( that never got its ) |
| Purple / checkered block | "Which picture did you mean?" | Is the file magic_rainbow.png, inside textures/, spelled exactly like tiles says? |
| Block with see-through holes | "Some dots are empty" | Back to Pixelorama โ fill every dot, export again |
| Nothing new in the inventory | "Did you restart at all?" | ๐ง ask a grown-up to put it in the game and look for the awake line./deploy.sh -r magic and look for the awake line |
| The line is red in the editor | "This is not a whole sentence" | Missing " or , or ) |
./deploy.sh -r magic โ the repo copy goes back into the game, and the old one was saved
in .backups/ first. Nothing can be lost.print = the computer talks back, and that's how you check it heard you
register = make a new thing exist
magic: = your family name, so nothing ever collides
description = the label people read; the real name never changes
tiles = the skin, and the filename must match exactly
light_source = a number you can twist and see
The Loop โ change โ deploy โ restart โ look
You did not "play with a game". You wrote instructions a computer obeyed, and you drew the art that made it visible. That is real programming, and it is finished, and it is yours.
A block that is awake. Right-click it and it says hello to you, by name โ and puffs sparkles out of the top.
When you're finished: a block called Answering Chime. Place one down, right-click it, and your own name comes back at you.
callback โ code that waits. You write it now, it does nothing
now, and it runs the moment something happens.Level 2 lives in its own folder: mods/magic_touch. Its first two lines look
exactly like the ones you already know:
-- A block that answers when you touch it.
print("[magic_touch] My answering block is awake!")
./deploy.sh -r magic_touch[magic_touch] My answering block is awake!Level 1 was magic:rainbow. This is magic_touch:chime.
magic_touch: is this mod's family โ the same as its folder name.
chime is the block's own name. Two mods can never share a family, the same way
two people in the same town can't both be the post office.Read the block and count how much you already recognise:
core.register_node("magic_touch:chime", {
description = "Answering Chime",
tiles = {"magic_touch_chime.png"},
on_rightclick = function(pos, node, clicker, itemstack, pointed_thing)
Four of those lines you already know from Level 1.
register_node โ make a block. "magic_touch:chime" โ its real name.
description โ the label people read. tiles โ the skin.
on_rightclick = function(โฆend, and then }). That lump is the new
thing. That lump is what a callback looks like.function โฆ end: a bag of things to do later ๐That's all function means. It bundles up some instructions and puts them in a
bag so they can be run later, when the moment comes. The end at
the bottom says that's the end of the bag.
Those five names are presents the game hands you at the moment it snaps. You do not fill them in โ the game fills them in. You just give them names so you can use them inside the bag.
| The name | The present is |
|---|---|
pos | where the block is (its x, y, z) |
node | which block it is |
clicker | who clicked it |
itemstack | what was in their hand |
pointed_thing | what their crosshair was on |
You will meet the same presents again at Level 8 with portals. They are always the same presents. Only the bag changes.
if clicker then
local name = clicker:get_player_name()
core.chat_send_player(name, "Ding! Hello, " .. name .. " - you woke me up!")
end
if clicker then โ "If there is actually a person hereโฆ"local name = clicker:get_player_name() โ "โฆtake their name and keep it in a box
called name"core.chat_send_player(name, โฆ) โ "โฆsend that person a chat message""Ding! Hello, " .. name
โ โ
"Ding! Hello, " stuck onto your real name
โ
"Ding! Hello, Jonathan - you woke me up!"
That is why the chime says your name and not somebody else's. It was never written in โ it got glued on, fresh, from whoever actually clicked.
if at all?
Because the bag can sometimes run when there is nobody there. If it tried to greet
nobody it would crash. if clicker then means "only do this if there is
a real person", and it saves us a whole family of breakages../deploy.sh -r magic_touchThe last lump inside the bag is one machine with a lot of dials. It looks scary. It is the
same idea over and over. add_particlespawner = "puff out a lot of tiny
pictures" โ each tiny picture is a particle.
min / max pair. min =
the smallest, max = the biggest. For every single sparkle the
game picks a random number between the two. That is why no two puffs are ever the same.| Dial | What it controls | Ours |
|---|---|---|
amount | how many sparkles in the puff | 14 |
time | how long the puff takes (0.001 = all at once) | 0.001 |
minpos / maxpos | the box they start in, around the block | just above it |
minvel / maxvel | how fast they fly | up and out |
minacc / maxacc | how gravity pulls them (-4 = down) | down |
minexptime / maxexptime | how long each sparkle lives, in seconds | 0.4 โ 1.2 |
minsize / maxsize | how big each sparkle is | 0.8 โ 1.6 |
glow | how shiny, like light_source | 10 |
texture | the tiny picture each sparkle wears | magic_touch_spark.png |
magic_touch_spark.png."Why this is worth learning
The min/max pattern is all over real game code. Once you can read it
here, you can read it anywhere.
1 ยท The words. Change the greeting โ anything inside the quotes:
core.chat_send_player(name, "WAKE UP SLEEPYHEAD, " .. name .. "!")
.. name .. exactly as it is
That is the bit that glues your actual name into the message. Delete it and the machine does
not know who to greet.2 ยท One dial. Pick exactly one, redeploy, look:
| Try | What happens |
|---|---|
amount = 60 | a lot more sparkles |
glow = 15 | bright enough to light the block |
maxexptime = 4 | the sparkles hang around for ages |
minacc = {x = 0, y = 1, z = 0} | gravity up โ they float away |
This is exactly what is in your mods/magic_touch/init.lua right now:
-- A block that answers when you touch it.
print("[magic_touch] My answering block is awake!")
core.register_node("magic_touch:chime", {
description = "Answering Chime",
tiles = {"magic_touch_chime.png"},
on_rightclick = function(pos, node, clicker, itemstack, pointed_thing)
if clicker then
local name = clicker:get_player_name()
core.chat_send_player(name, "Ding! Hello, " .. name .. " - you woke me up!")
end
core.add_particlespawner({
amount = 14,
time = 0.001,
minpos = {x = pos.x - 0.3, y = pos.y + 0.8, z = pos.z - 0.3},
maxpos = {x = pos.x + 0.3, y = pos.y + 1.2, z = pos.z + 0.3},
minvel = {x = -0.5, y = 1.0, z = -0.5},
maxvel = {x = 0.5, y = 2.5, z = 0.5},
minacc = {x = 0, y = -4, z = 0},
maxacc = {x = 0, y = -1, z = 0},
minexptime = 0.4,
maxexptime = 1.2,
minsize = 0.8,
maxsize = 1.6,
glow = 10,
texture = "magic_touch_spark.png",
})
end,
})
If you changed the greeting yours has your words in that one line instead. That is allowed โ the words are free.
| What you see | The game is asking | What to do |
|---|---|---|
ModRunError + a line number | "I got lost on line N" | A function needs its end. Count your bags. |
expected ')' near 'end' | "A bracket is still open from earlier" | Find the ( that never got its ) |
attempt to call field 'get_player_name' (a nil value) | "'who clicked' was empty โ there was nobody" | That is what if clicker then is for. Check it is still there |
attempt to concatenate a nil value | "you told me to glue words onto something that isn't there" | name must be spelled the same in all three places |
| Right-click places a block instead | "are you touching the chime, or just pointing near it?" | Aim at the chime itself. If it still places, empty your hand and right-click again |
| Message works, no sparkles | "those are two separate machines" | Look inside add_particlespawner โ is a dial 0? Is the texture name wrong? |
| Sparkles are invisible | "I have no picture to wear" | Is it magic_touch_spark.png, inside textures/, spelled exactly like the code says? |
| Nothing new in the inventory | "did you restart at all?" | ๐ง ask a grown-up to put it in the game, then look for the awake line./deploy.sh -r magic_touch, then look for the awake line |
./deploy.sh -r magic_touch โ repo copy back into the game, old copy saved in
.backups/ first. Nothing can be lost.callback = code that waits instead of running right now
on_rightclick = the thing that makes it snap
function โฆ end = a bag of instructions to run later
the five presents โ pos, node, clicker,
itemstack, pointed_thing
.. = glue for words, and that is how your name got into the message
if clicker then = do not try to greet nobody
min / max = the game picks a random number between them, every time
Level 1 made a thing exist. Level 2 made a thing happen. That is a bigger step than it sounds like.
Three blocks that are almost nothing to look at, and completely different to walk on.
| The block | What it does to you |
|---|---|
| Slippery Rainbow Ice | you slide |
| Ghost Block | you walk straight through it |
| Magic Looking Glass | you see through it, but you can't walk through it |
groups โ a bag of labels with numbers in it. The game reads the bag and decides how
the block behaves.Level 3 lives in mods/magic_terrain.
./deploy.sh -r magic_terrain[magic_terrain] My three feeling-blocks are awake!core.register_node("magic_terrain:ice", {
description = "Slippery Rainbow Ice",
tiles = {"magic_terrain_ice.png"},
groups = {slippery = 5},
})
Why a bag instead of one line? Because you can put lots of labels in the same bag:
groups = {slippery = 5, cracky = 2},
That block is slippery and breakable with a pick. Level 1 had one number doing
one job. A groups bag is how you give a block a whole
personality without writing any real instructions.
This is not our made-up list โ the game's own ice is:
groups = {cracky = 3, cools_lava = 1, slippery = 3},
So our ice is slippery = 5 and the game's own ice is
slippery = 3. Go and walk on both. Which slides more? That is a
lab question, not a code question โ only you can tell us.
| Label | What it tells the game |
|---|---|
slippery | you slide on it |
cracky | a pickaxe breaks it |
crumbly | a shovel breaks it |
choppy | an axe breaks it |
snappy | shears cut it |
immortal | nothing breaks it |
core.register_node("magic_terrain:ghost", {
description = "Ghost Block",
tiles = {"magic_terrain_ghost.png"},
walkable = false,
})
false
Some questions have exactly two answers. The computer writes them as true and
false.walkable = false โ "Can you walk on this? No."Notice there is no bag here. This one is a single switch sitting on its own.
Some things go in the groups bag; some things are one line of their own.
false without quotes is the yes/no answer. "false" with quotes is the
word. Those are not the same thing, and the computer never guesses which one you
meant.core.register_node("magic_terrain:glass", {
description = "Magic Looking Glass",
tiles = {"magic_terrain_glass.png"},
drawtype = "glasslike",
use_texture_alpha = "blend",
})
Two new lines, and they are about something different entirely: not how the block behaves, but how the game draws it.
drawtype โ the style the game paints it inuse_texture_alpha โ please actually show the see-through bitsA picture can have see-through dots in it. That's what "alpha" means: how see-through each dot is. But by default the game throws the see-through parts away and treats your picture as solid.
use_texture_alpha = "blend"
โ
"some of my dots are see-through โ really show that, don't throw it away"
You are going to guess first, then test. That order is the whole method.
| Question | Guess out loud | Then test |
|---|---|---|
| Which bridge do you slide off? | ||
| Can you walk through the glass doorway? | ||
| Can you walk through the ghost doorway? | ||
| Can you see through the floor of the ghost bridge? | ||
| Can you stand inside a ghost block? |
One dial at a time. Deploy. Test. Then the next.
The slippery number. Try 1. Then 3 โ the game's own
ice. Then 99. Does 99 slide more than 5, or is 5 already as slidey as it
gets? Nobody told the computer what the biggest number is. Go find out.
The walkable switch. Change false to true. Walk on
the ghost. What changed? Change it back.
The see-through line. Delete this whole line from the glass and redeploy:
use_texture_alpha = "blend",
Go look at your glass. That is what it looks like when the game throws your see-through dots away. Then put the line back, deploy again, and watch the glass come back.
This is exactly what is in your mods/magic_terrain/init.lua right now:
-- Three blocks that FEEL completely different.
print("[magic_terrain] My three feeling-blocks are awake!")
-- 1. SLIPPERY - you slide off it.
core.register_node("magic_terrain:ice", {
description = "Slippery Rainbow Ice",
tiles = {"magic_terrain_ice.png"},
groups = {slippery = 5},
})
-- 2. GHOST - you walk straight through it.
core.register_node("magic_terrain:ghost", {
description = "Ghost Block",
tiles = {"magic_terrain_ghost.png"},
walkable = false,
})
-- 3. GLASS - you can see right through it, but you cannot walk through it.
core.register_node("magic_terrain:glass", {
description = "Magic Looking Glass",
tiles = {"magic_terrain_glass.png"},
drawtype = "glasslike",
use_texture_alpha = "blend",
})
| What you see | The game is asking | What to do |
|---|---|---|
ModRunError + a line number | "I got lost on line N" | Count braces โ a { needs its } |
| Only one block in the inventory | "I only got as far as the first one" | Find the error line; the blocks below it never got registered |
| The glass is a solid opaque brick | "you told me to throw the see-through away" | Put use_texture_alpha = "blend" back |
| You fall through the glass | "you set walkable = false on the wrong block" | Only the ghost should have walkable = false |
| You cannot find the ghost block | "it is mostly see-through, on purpose" | Place it against a wall, or find it with your crosshair |
| The ice is not slippery | "are you walking on it?" | Slippery only shows when you walk and try to stop or turn |
| Purple / checkered block | "which picture did you mean?" | Check magic_terrain_ice.png etc. inside textures/ |
attempt to index โฆ nil | "I have never heard of that name" | Check the spelling of groups, walkable, drawtype |
./deploy.sh -r magic_terrain โ repo copy back into the game, old copy saved first.
Nothing can be lost.groups = a bag of labels with numbers, and the game decides what they mean
You do not have to know how slippery works to make something slippery
true / false = the computer's yes and no, and no quotes this time
drawtype = pick a drawing style the game already has
use_texture_alpha = "really show my see-through dots"
The lab method: guess out loud first, then test, then report what surprised you
The removal method: take one line out and see what goes missing
A Star Wand. You swing it at any block and that block turns into a glowing Star-Painted Block.
item and node โ and the difference between them../deploy.sh -r magic_wand[magic_wand] My star wand is awake!Open the file and look at the two big blocks inside it:
core.register_node("magic_wand:painted", { -- โ one kind of thing
...
core.register_tool("magic_wand:star", { -- โ a DIFFERENT kind of thing
register_node and register_tool. That difference is the
whole level. Everything else is small.-- The paint. A block the wand can turn other blocks into.
core.register_node("magic_wand:painted", {
description = "Star-Painted Block",
tiles = {"magic_wand_painted.png"},
light_source = 8,
})
If that was easy, that is the point Level 1 taught you to read it.
This is the big idea. Read this table out loud.
node | item | |
|---|---|---|
| what it is | a place in the world | a thing you carry |
| the verb | you place it | you hold it |
| made by | core.register_node | core.register_tool |
| in our mod | magic_wand:painted | magic_wand:star |
| where it lives | in the ground, the wall, the sky | in your bag, or your hand |
| one you already know | magic:rainbow from Level 1 | this is your first item |
Your Level 1 rainbow block is a node. It sits exactly where you put it, with an x, y, z forever. The wand is an item. It has no position at all โ it is wherever you are. You cannot "place" a wand in the world the way you place a block. It lives in a hand or in a bag.
core.register_tool("magic_wand:star", {
description = "Star Wand",
inventory_image = "magic_wand_star.png",
wield_image = "magic_wand_star.png",
Two picture lines, because you look at a bag differently than you look at your own hand.
| Line | Where you see it |
|---|---|
inventory_image | the small square in your bag |
wield_image | the big one in your hand, right in front of your eyes |
Ours is the same picture both times โ but it does not have to be. You could draw a tiny neat star for the bag and a big sparkly one for the hand.
wield_image you need
to fix, not inventory_image. Two different problems, two different lines.| Level 2 | Level 4 | |
|---|---|---|
| the bag | on_rightclick = function(โฆ) | on_use = function(โฆ) |
| what makes it snap | you right-click the block | you swing the item |
| who is inside | clicker | user |
This is not a new idea. Same idea, different trigger. In Level 2 the block waited for a touch. In Level 4 the wand waits for a swing.
on_use = function(itemstack, user, pointed_thing)
Only three presents this time, not five โ an item does not need as many. And
pointed_thing came all the way from Level 2. Same present, same name:
what the crosshair is pointing at.
if not user then
return
end
not user means "there is no user".return is the emergency exit out of the bag. Everything below it never
happens.
if pointed_thing.type ~= "node" then
core.chat_send_player(name, "Aim the wand AT a block, not at the sky!")
return
end
.type = "what kind of thing is this?" When your crosshair is on
a real block the kind is "node". When it is on nothing, it is not
"node".
| Symbol | Means |
|---|---|
= | is the same as |
~= | is not the same as |
~ is the tilde
On your keyboard it sits next to the 1. A little squiggle that means "opposite of
equal". Easy to mix up with = โ and when you do, the wand either paints everything
or nothing at all. core.set_node(pointed_thing.under, {name = "magic_wand:painted"})
register_node,
register_tool โ you were adding to the game's lists. You never touched the world.
This line changes a block that is already out there into a different block.| Bit | What it means |
|---|---|
core.set_node( | "change what is at this position" |
pointed_thing.under | "the block you are pointing at" |
{name = "magic_wand:painted"} | "become this" |
your crosshair
+
| โ pointed_thing.under (the solid block you aimed at) โ THIS one changes
./deploy.sh -r magic_wandPaint a path across a field โ a glowing road is one afternoon of clicking.
Paint a picture on the side of a hill: painted blocks are pixels and the hill is
the canvas. Paint a whole tree and stand back โ it glows at
light_source = 8. Paint at night and see how far the glow
reaches.
This is exactly what is in your mods/magic_wand/init.lua right now:
-- A thing you HOLD, not a thing you place.
print("[magic_wand] My star wand is awake!")
-- The paint. A block the wand can turn other blocks into.
core.register_node("magic_wand:painted", {
description = "Star-Painted Block",
tiles = {"magic_wand_painted.png"},
light_source = 8,
})
-- The wand itself.
core.register_tool("magic_wand:star", {
description = "Star Wand",
inventory_image = "magic_wand_star.png",
wield_image = "magic_wand_star.png",
on_use = function(itemstack, user, pointed_thing)
if not user then
return
end
local name = user:get_player_name()
if pointed_thing.type ~= "node" then
core.chat_send_player(name, "Aim the wand AT a block, not at the sky!")
return
end
core.set_node(pointed_thing.under, {name = "magic_wand:painted"})
core.chat_send_player(name, "Painted one block.")
end,
})
| What you see | The game is asking | What to do |
|---|---|---|
ModRunError + a line number | "I got lost on line N" | Count brackets โ every ( needs its ) |
| "Aim the wand AT a block" when you were aiming at a block | "was your crosshair on empty space?" | Aim at the middle of a face, not the edge or the corner |
| The block behind the one you aimed at changed | "you hit the edge, so I used the block past it" | Same fix โ aim at the middle of the block's face |
| Nothing happens at all | "is the wand even in your hand?" | Check you are holding Star Wand, not a block |
| "Aim at a block" forever, even pointing at dirt | "is ~= actually ~=?" | Check you have ~= and not = โ one character, whole different machine |
attempt to index 'pointed_thing' (a nil value) | "look at a thing that isn't there" | Check the spelling of pointed_thing in every line |
| Painted block is purple | "which picture did you mean?" | magic_wand_painted.png inside textures/, spelled exactly like tiles says |
| Wand not in your inventory | "did you restart at all?" | ๐ง ask a grown-up to put it in the game, look for the awake line./deploy.sh -r magic_wand, look for the awake line |
./deploy.sh -r magic_wand โ repo copy back into the game, old one saved to
.backups/ first. Nothing can be lost.A node is a place. An item is a thing. A node has a position; an item has a hand
core.register_node makes a block, core.register_tool makes a thing you hold
inventory_image = the bag picture, wield_image = the hand picture
on_use is Level 2's waiting spell with a different trigger
not = the opposite of, and return = stop right now
~= = not the same as (the squiggle means "opposite of equal")
core.set_node(โฆ) = the first time your code changed the world
Level 1 made things exist. Level 2 made them answer. Level 3 made them feel. Level 4 put one of your things in your hand โ and let your code reach out and change the world.
The Rainbow Lantern โ except you are not allowed to just take it. A log becomes planks. Planks become sticks. One stick and four planks become a lantern that glows.
recipe โ which is one new form with four blanks in it. That is
all. Everything you fill a blank with, you can already read../deploy.sh -r magic_craft.
Steps 1โ8 are us reading every line. Step 9 is yours.[magic_craft] My crafting chain is awake!Here is something strange. Go and look at the whole file.
There is not one function in it.
| Level | what the code was |
|---|---|
| Level 1 | "make this thing exist" |
| Level 2 | "wait for a touch, then do these things" |
| Level 3 | "here is a bag of labels, behave accordingly" |
| Level 4 | "wait for a swing, then change the world" |
| Level 5 | "here is a form. Filling it in is the whole job." |
-- Things you have to MAKE before you are allowed to have them.
print("[magic_craft] My crafting chain is awake!")
Level 5 registers exactly four things. All in one look:
-- The start of everything. The only thing you get for free.
core.register_node("magic_craft:log", {
...
-- Planks. Not on the free shelf - these have to be made.
core.register_node("magic_craft:plank", {
...
-- Not a block at all. A thing you carry that does nothing on its own.
core.register_craftitem("magic_craft:stick", {
...
-- The prize. It glows, and there is no way to take one.
core.register_node("magic_craft:lantern", {
...
| Name | what kind of thing | free in your creative bag? |
|---|---|---|
magic_craft:log | a node (Level 4!) | โ yes โ the one free thing |
magic_craft:plank | a node | ๐ no |
magic_craft:stick | a craft item | ๐ no |
magic_craft:lantern | a node that glows | ๐ no |
Open the file and find this line:
groups = {choppy = 2, not_in_creative_inventory = 1},
groups = {...} is a bag of labels and the game reads the bag
to decide how a thing behaves. Two labels in this bag:| Label | what it tells the game |
|---|---|
choppy = 2 | "wood. An axe is the right tool for me." (The game's own apple tree uses choppy = 2 too.) |
not_in_creative_inventory = 1 | "do not put me on the free shelf." |
That second label is the lock on the door. Not new technology โ the same bag from Level 3 doing a new job. 121 files in the game itself use that exact label, which is why you can trust it.
core.register_craft ๐core.register_craft({
recipe = {
{"magic_craft:log"},
},
output = "magic_craft:plank 4",
})
| The blank | what it means |
|---|---|
recipe = { ... } | the shape you lay out on the crafting grid |
a row {"a", "b"} | one row of the grid, left to right |
"" | an empty square โ and it has to stay empty |
output = "name 4" | what you get. The space and the 4 mean how many |
output = "magic_craft:plank 4"
The 4 is inside the quotation marks, with a space before it. It is
not output = "magic_craft:plank", 4. One space, inside the quotes โ that is where
this line breaks, so look at it every time you change it.In creative mode your inventory already has a crafting grid built in:
your grid (3 x 3) the result
+-----+-----+-----+ +-----------+
| 1 | 2 | 3 | | |
+-----+-----+-----+ ===> | shows |
| 4 | 5 | 6 | | HERE |
+-----+-----+-----+ +-----------+
| 7 | 8 | 9 |
+-----+-----+-----+
Nine squares in. One square out. Drag things into the nine, and if they make a shape that matches a recipe, the thing you made appears on the right. Click it and it comes into your bag.
core.register_craft({
recipe = {
{"magic_craft:plank"},
{"magic_craft:plank"},
},
output = "magic_craft:stick 4",
})
Look at the shape. Two rows. One square wide. Stacked. Now guess before you test. Nobody learns anything from guessing after.
| What you put in the grid | Your guess | What actually happened |
|---|---|---|
| two planks, one above the other | ? | |
| two planks, side by side | ? | |
| one plank only | ? | |
| three planks stacked | ? |
The reason side-by-side can fail: the recipe says stacked. The game does not turn your shape around to be helpful. It looks for the shape exactly as written.
core.register_craft({
recipe = {
{"magic_craft:plank", "magic_craft:plank"},
},
output = "magic_craft:stick 4",
})
The last recipe, and the one you actually care about:
core.register_craft({
recipe = {
{"magic_craft:plank", "", "magic_craft:plank"},
{"", "magic_craft:stick", ""},
{"magic_craft:plank", "", "magic_craft:plank"},
},
output = "magic_craft:lantern",
})
+-----+-----+-----+
| p | | p | p = plank
+-----+-----+-----+ . = empty (the "" you type)
| | s | | s = stick
+-----+-----+-----+
an X
"" is for
It means "this square must be empty". It is not a gap you left because you
were lazy โ it is you telling the game the middle of each edge stays empty. Take the
"" out and the row only has two squares, so the shape becomes something else
entirely and nothing gets crafted.Notice four planks and one stick. A recipe can ask for more than one kind of thing.
[log] --recipe 1--> 4 planks
1 log
2 planks --recipe 2--> 4 sticks
4 planks + 1 stick --recipe 3--> THE LANTERN
./deploy.sh -r magic_craft| Change | To | What happens |
|---|---|---|
| how generous a log is | output = "magic_craft:plank 8", | one log, eight planks โ your whole chain just got twice as easy |
| how bright the lantern is | light_source = 14, | 12 is bright; 14 is the brightest the game allows. Stand next to it at night |
| break a shape on purpose | turn the X sideways, stick in a corner | the result square stays empty โ now you have seen a failed lookup |
magic_craft:plank has to be spelled exactly the same in the recipe as in the
registration. The recipe looks things up by name, and a wrong name is a lookup
that can never succeed โ it will not even tell you, it will just never craft.This is exactly what is in your mods/magic_craft/init.lua right now:
-- Things you have to MAKE before you are allowed to have them.
print("[magic_craft] My crafting chain is awake!")
-- ========== THE FOUR THINGS ==========
-- The start of everything. The only thing you get for free.
core.register_node("magic_craft:log", {
description = "Magic Wood Log",
tiles = {"magic_craft_log.png"},
groups = {choppy = 2},
})
-- Planks. Not on the free shelf - these have to be made.
core.register_node("magic_craft:plank", {
description = "Rainbow Plank",
tiles = {"magic_craft_plank.png"},
groups = {choppy = 2, not_in_creative_inventory = 1},
})
-- Not a block at all. A thing you carry that does nothing on its own.
core.register_craftitem("magic_craft:stick", {
description = "Rainbow Stick",
inventory_image = "magic_craft_stick.png",
groups = {not_in_creative_inventory = 1},
})
-- The prize. It glows, and there is no way to take one.
core.register_node("magic_craft:lantern", {
description = "Rainbow Lantern",
tiles = {"magic_craft_lantern.png"},
light_source = 12,
groups = {choppy = 2, not_in_creative_inventory = 1},
})
-- ========== THE THREE RECIPES ==========
-- One log, anywhere on the grid, becomes four planks.
core.register_craft({
recipe = {
{"magic_craft:log"},
},
output = "magic_craft:plank 4",
})
-- Two planks STACKED, one on top of the other, become four sticks.
core.register_craft({
recipe = {
{"magic_craft:plank"},
{"magic_craft:plank"},
},
output = "magic_craft:stick 4",
})
-- Four planks in the corners and one stick in the middle makes a lantern.
core.register_craft({
recipe = {
{"magic_craft:plank", "", "magic_craft:plank"},
{"", "magic_craft:stick", ""},
{"magic_craft:plank", "", "magic_craft:plank"},
},
output = "magic_craft:lantern",
})
| What you see | The game is asking | What to do |
|---|---|---|
| The result square stays empty | "is your shape exactly the shape?" | Same rows, same order, empty squares kept empty |
| Empty, but the shape looks right | "is it turned around or upside down?" | Luanti does not rotate your shape. Put it the way the recipe is written |
| Empty, shape looks perfect | "is there an empty square you filled?" | The "" squares must be empty in the grid too |
ModRunError + a line number | "I got lost on line N" | Count brackets โ every { needs its } |
output gives you 1 instead of 4 | "where is the number?" | output = "magic_craft:plank 4" โ space then number, inside the quotes |
| Nothing crafts, nothing looks wrong | "did you spell the name the same in both places?" | The name in the recipe must match the registered name character for character |
| You found a lantern in your creative bag | "wait โ you should NOT be able to do that" | not_in_creative_inventory = 1 is missing or misspelled. That label is the whole lock |
| A block is purple / unknown | "which picture did you mean?" | magic_craft_log.png, _plank, _stick, _lantern in textures/, spelled exactly like tiles / inventory_image says |
| The lantern does not glow | "how bright did you set it?" | light_source = 12 (0 = dark, 14 = brightest) |
| Not even awake | "did you restart at all?" | ๐ง ask a grown-up to put it in the game, look for the awake line./deploy.sh -r magic_craft, look for the awake line |
./deploy.sh -r magic_craft โ repo copy back into the game, the old one was saved to
.backups/ first. Nothing can be lost.recipe = one new form with four blanks.
Filling it in is the whole job
core.register_craft does not wait for anything and runs no code โ
it just adds an entry to the crafting table's list
recipe = { {"a"}, {"a"} } is a shape: rows and squares
"" = an empty square that must stay empty
output = "magic_craft:plank 4" โ the count lives inside the quotes
The shape must match exactly. No rotating. No helping you out.
A one-square shape fits anywhere in the 3ร3; a big shape has to be right
The lock on the free shelf is a Level 3 label:
not_in_creative_inventory = 1
You made something you could not get any other way โ and you decided
how hard that was
Levels 1 to 4 were all "make a thing exist". Level 5 is the first level where you wrote down how things turn into other things. That is the beginning of systems.
Challenge answer: three lanterns take four logs. The leftovers from each lantern are not enough to start the next one, so the last log is the one that finishes the job. Counting leftovers is a real programming skill โ half of debugging is knowing where your things went.
Every level teaches one new word and makes one new thing you can see. Levels 1โ2โ3โ4 build on each other, so do those before jumping ahead.
You made: a block that never existed before. You named it, drew it, placed it, made it glow.
New word: register
You made: the Answering Chime โ right-click it and it greets
you by name and puffs sparkles out of the top.
New word: callback
You made: three blocks โ Slippery Rainbow Ice,
Ghost Block (walk straight through) and Magic Looking Glass
(see through, but not walk through).
New word: groups โ a bag of labels with numbers in it.
cracky = 3 means "this breaks with a pick, at speed 3".
slippery = 5 means "you slide off". The game reads the bag and decides how the
block behaves.
This is where you stop typing words and start tuning.
You made: the Star Wand โ swing it at a block and it turns
into a glowing Star-Painted Block.
New word: item vs node
A node is a place in the world. An item is a thing you carry.
Your rainbow block is a node. Your wand is an item. Same idea, different verbs.
You made: the Rainbow Lantern โ out of a log, through
planks and sticks, using three recipes. You cannot take one from the creative bag.
That was the point.
New word: recipe โ one new form with four blanks.
recipe = { ... } is the shape on the grid,
output = "name 4" is what you get, and
"" is a square that must stay empty.
This is design, not computer rules The first level where the game gets harder on purpose: you cannot get the cool thing until you make the boring thing first. You decided that.
You will: make a rainbow helmet, chestplate, leggings and boots โ and when you put them on you can see them on your own character. And they really protect you. Different armour stops different damage.
armor_groups = what this stops, and how much. armor_use = how many hits
before it breaks.You will: invent a material โ say stormsteel โ that has to be made a special way, is hard to dig, does not burn, is heavy to carry, and makes good armour against lightning but bad armour against fire.
Why it comes later It is really Levels 3 + 5 + 6 holding hands.
8.1 โ one block in, one block out. Step into a rainbow block here โ you are
somewhere else. No animation, no fuss. Just there instead of here.
New word: teleport, plus the idea of remembering where the other end is.
8.2 โ a real door: 4 wide, 5 tall. You build the frame out of rainbow blocks and the inside becomes the portal. Now the game has to understand a shape, not one block. This is where you learn to think in coordinates: is the player inside the frame, or beside it?
8.3 โ a locked door. The portal does nothing unless you are holding the right thing. Now your portal has a rule, not just a place. Two doors, two keys, two worlds.
8.4 โ the door remembers. After the server restarts, your portals still work.
New word: save โ most things your mod makes are forgotten at restart, so learning what
to write down and where is the difference between a toy and a world.
You will: type /magic in the chat and your mod answers โ which blocks
you made, where they are, how to use them.
/help is.1 a block exists โ
done
2 it answers when you touch it โ
done
3 numbers change how it feels โ
done
4 things you hold instead of place โ
done
5 crafting โ make it before you get it โ
done
6 armour you can see on yourself
7 a whole new material with a personality
8 portals (one block โ a real door โ locked โ remembers)
9 your mod answers /magic
One new word. One new thing you can see. Then stop and play with it. That is the whole method.