Ourcraft Manual

Everything you need to play Ourcraft and its team game, Splat Squad. New players can start with Getting started and Controls.

1. Getting started

The easiest way: download the game for macOS, Windows or Linux, unzip it and open it. To build it yourself from its source code with Rust instead (a few minutes the first time; after that it starts in seconds):

  1. Install Rust from rustup.rs (one command; accept the defaults).
  2. Get the game:
    git clone https://github.com/rsantacroce/ourcraft
    cd ourcraft
  3. Start it:
    cargo run --release
    You'll land on the main menu.
Linux: you may need these packages first (Ubuntu/Debian names): sudo apt install pkg-config libasound2-dev libudev-dev libwayland-dev libxkbcommon-dev
Shortcuts. You can skip the menu from the command line: cargo run --release -- --world "My World" opens (or creates) a world, and --connect 192.168.1.20 --name Sam joins a friend.
The main menu

Making a new world

In a world, press Esc (or the Menu button on touch screens) for the pause menu: Back to game, Settings, or Save and quit to title.

3. Controls

Click inside the game window to capture the mouse; press Esc to get it back.

ActionKeyboard & mouseGamepadTouch
WalkW A S DLeft stickThumb on the left side, drag
Look aroundMove the mouseRight stickDrag on the right side
JumpSpaceAJump button (steps are climbed automatically)
RunCtrlClick the left stickPush the joystick all the way
Fly on / off (creative)Double-tap Space, or FXFly button
Fly or swim up / downSpace / ShiftA / BJump / Down
Break a block / use a gadgetLeft click (hold to repeat)Right triggerPress and hold
Place a blockRight clickLeft triggerQuick tap
Use a door, chest, furnace, crafting table, bed or signRight click (hold Shift to place a block against it instead)Left triggerQuick tap
Eat (food in hand, survival)Hold right clickHold left triggerHold the Eat button
Pet, feed or shear an animalRight click on itLeft triggerQuick tap
Bop a monster (or an animal: it hops away)Left click on itRight triggerPress
Drop one item (Ctrl: the whole stack)Q
Copy the block you're looking at (creative)Middle click (can be switched off in Settings)D-pad up
Camera: first person → behind you → in front of youF5D-pad downView button
Choose a hotbar slot1–9 or mouse wheel (the wheel can be switched off in Settings)BumpersTap the slot
InventoryEYBag button
Chat / commandEnter / /
Pause menuEscMenu button
Show or hide info textF3
View distance[ and ]In Settings
Skip ahead an hourT
Creative ↔ survivalG

4. Playing Ourcraft

A view over hills, forest and a beach

Moving around

Walk with WASD and look with the mouse. You can jump up one block at a time. In water you float: hold Space to swim up. In creative mode, double-tap Space to fly, and land by flying down onto the ground.

Building and breaking

Hotbar and inventory

The nine squares at the bottom are your hotbar. The selected one has a white border, and its name shows above it. Press E to open the inventory.

The creative block picker

Creative and survival

CreativeSurvival
BlocksEndless supply of every blockOnly what you collect; placing uses it up
BreakingInstant; blocks just disappearTakes a moment (quicker with the right tool); the block drops as an item to pick up (stone gives cobblestone, grass gives dirt)
FlyingYesNo
Health and hungerNoYes (gentle)
MonstersLeave you aloneCome out at night (unless the world is peaceful)

Pick one when you make a world. You can switch any time with G.

The world

Blocks

BlockWhere to find it / notes
Grass, DirtEverywhere on the surface
Stone, CobblestoneUnder the dirt; breaking stone gives cobblestone
SandDeserts and beaches
GravelThe bottom of lakes and seas
Log, Leaves, PlanksTrees; planks are for building
Snowy GrassSnowy lands and mountain tops
CactusDeserts
GlassSee-through, great for windows
BricksFor houses and walls
LampGlows, even at night
WaterLakes and seas; you can swim in it
BedrockThe bottom of the world; can't be broken
Coal, Iron, Gold, Diamond OreUnderground; deeper means rarer. Need a pickaxe (iron: stone or better; gold and diamond: iron or better)
ClayUnder lakes and the sea; gives clay balls for bricks
LavaThe bottom of deep caves; glows, and stings if you fall in
Crafting Table, Furnace, ChestCrafted; right click to use
TorchCrafted from coal and a stick; lights up caves
Stairs, SlabsWood, cobblestone, stone and brick; you walk up them without jumping
Fence, Door, Trapdoor, Ladder, Sign, BedCrafted from wood (the bed needs wool)
WoolFrom shearing sheep
Blocks of Iron, Gold, Diamond9 ingots (or diamonds): shiny!
Paint (8 colours), Rainbow LampFrom the Paint Blocks mod
Snow Bricks, Ice LanternFrom the Snow Fun mod (/snowman, /snowballs)

5. Survival guide

In survival you start with empty hands. Here's one way to get going; there's no wrong way to play.

Your first day

  1. Find a tree and hold left click on its logs (by hand it takes a couple of seconds). Walk over the logs that pop out to pick them up.
  2. Press E. Put a log in the little crafting grid: it makes 4 planks. Click the planks to take them.
  3. Fill the 2×2 grid with planks to make a crafting table. Place it and right click it: now you have a 3×3 grid.
  4. Make sticks (two planks, one on top of the other), then a wooden pickaxe.
  5. Dig down into the stone to get cobblestone. Make stone tools, and a furnace (8 cobblestone in a ring).
  6. Look for black-speckled coal ore and make torches. Light up a little shelter before the night, and make a bed (wool and planks) so you can sleep through it.

Tools and ores

Crafting recipes

Put the items in the grid in this shape (it can go anywhere in the grid, and the mirror image works too). A dot is an empty square. Recipes up to 2×2 work in your inventory; bigger ones need a crafting table.

MakesShapeWith
4 PlanksLL = log
4 SticksP / PP = planks
Crafting TablePP / PPP = planks
PickaxeXXX / .#. / .#.X = planks, cobblestone, iron ingot or diamond; # = stick
AxeXX / X# / .#
ShovelX / # / #
FurnaceCCC / C.C / CCCC = cobblestone
4 TorchesC / #C = coal, # = stick
ChestPPP / P.P / PPPP = planks
BedWWW / PPPW = wool, P = planks
3 DoorsPP / PP / PPP = planks
2 TrapdoorsPPP / PPPP = planks
3 FencesP#P / P#PP = planks, # = stick
Fence Gate#P# / #P## = stick, P = planks
3 Ladders#.# / ### / #.## = stick
3 SignsPPP / PPP / .#.P = planks, # = stick
4 StairsX.. / XX. / XXXX = planks, cobblestone, stone or bricks
6 SlabsXXX
Shears.I / I.I = iron ingot
BucketI.I / .I.I = iron ingot
Bricks (block)BB / BBB = brick (from clay balls in the furnace)
2 LampsGGG / GCG / GGGG = glass, C = coal
Block of Iron/Gold/DiamondXXX / XXX / XXXX = ingots or diamonds (and back: one block gives 9)
Golden AppleGGG / GAG / GGGG = gold ingot, A = apple

The furnace

Right click a furnace. Put what you want to cook in the top slot and fuel in the bottom one: coal burns longest; logs, planks, sticks and wooden tools work too. The flame shows the fire, the arrow how far the cooking is, and the result appears on the right. It keeps cooking while you're away.

Health and food

Monsters at night (and in caves)

At night, and in dark caves at any time, two silly monsters come out near players in survival: the Grumble (a grumpy teal fellow in purple shorts) and the Bouncer (a purple jelly that hops), the Puff (a little floating cloud) and the Rumble (a slow rock with glowing eyes). They follow you and bonk you for a heart or half a heart. Bop them back with left click: a few hits (fewer with a tool) and they vanish in confetti, sometimes leaving a lump of coal. At sunrise the ones outside puff away (cave monsters stay in their caves). They never appear where torches or lamps light things up, so light your house and your mine, and a bed skips the night.

Don't want monsters at all? Type /peaceful: no monsters and no hunger, for the whole world (type it again to switch back).

Doors, stairs, chests, signs, beds

Farming

  1. Make a hoe and right click dirt or grass with it: it becomes farmland. Farmland near water (up to 4 blocks away) turns dark and wet, and plants grow faster on it. Plants need light: the open sky (glass is fine, for a greenhouse) or a torch or lamp nearby. Mushrooms grow in the dark.
  2. Get seeds by breaking tall grass (or the ferns in forests). Right click farmland with them to plant. Carrots and potatoes are planted as they are; you find them growing wild in meadows now and then.
  3. Wait a few minutes. When wheat is golden, break it: you get wheat and more seeds. Breaking a plant too early just gives the seed back.
MakesShapeWith
HoeXX / .# / .#X = planks, cobblestone, iron ingot or diamond; # = stick
BreadWWWW = wheat
8 CookiesWSWW = wheat, S = sugar
CakeMMM / SES / WWWM = milk bucket, S = sugar, E = egg, W = wheat
Pumpkin Piepumpkin + sugar + eggany squares
4 BowlsP.P / .P.P = planks
Beetroot Soupbowl + 6 beetrootsany squares
Mushroom Stewbowl + red + brown mushroomany squares
Sugarsugar cane
3 PaperCCCC = sugar cane
4 Pumpkin Seedspumpkin
Melon Seedsmelon slice
MelonMMM / MMM / MMMM = melon slice
Pumpkin LanternP / TP = pumpkin, T = torch (it glows!)
ComposterP.P / P.P / PPPP = planks

In the furnace a potato becomes a baked potato. Foods and how filling they are: cookie and melon slice a little, carrot and bread more, baked potato and soups a lot, pumpkin pie the most.

Colours

Flowers grow in patches in the meadows. Put a flower in the crafting grid to get a dye. There are sixteen colours:

What you can colour:

MakesHow
Coloured woolwhite wool + a dye (any squares)
A coloured bedWWW / PPP: three wool of one colour over three planks
3 CarpetsWW: two wool side by side
8 Stained glass8 glass around a dye (see-through and coloured)
8 Clay tiles8 clay blocks around a dye

Right click a sheep with a dye to colour its wool: shearing it gives wool of that colour, and it grows back the same colour. Some wild sheep are already gray, black or brown, and lambs take after their parents.

Trees, boats and stone

Fishing, bows, armour and gadgets

MakesShapeWith
Fishing Rod..# / .#S / #.S# = stick, S = string
Bow.#S / #.S / .#S# = stick, S = string
4 ArrowsF / # / EF = flint, # = stick, E = feather
4 Stringwoolany colour
Target.R. / RWR / .R.R = red wool, W = white wool
Helmet, Chestplate, Leggings, BootsXXX / X.X, X.X / XXX / XXX, XXX / X.X / X.X, X.X / X.XX = wool, iron ingot, gold ingot or diamond
Compass.I. / ICI / .I.I = iron ingot, C = coal
Clock.G. / GCG / .G.G = gold ingot, C = coal
MapPPP / PCP / PPPP = paper, C = compass
SpyglassG / I / IG = glass, I = iron ingot
2 RopeSS. / SS. / ..SS = string
SaddleWWW / S.S / I.IW = wool, S = string, I = iron ingot
Campfire.#. / #C# / LLL# = stick, C = coal, L = logs

Decorating your home

Spark circuits and rails

Spark is a glowing blue power found deep underground in spark ore (below the iron, and you need an iron pickaxe). It gives spark dust: place it on the ground as wire. Wire reaches out to the wire, levers, lamps and other spark things next to it, so you can see which way it goes.

MakesShapeWith
Lever# / C# = stick, C = cobblestone
Buttonstone
Pressure PlateSSS = stone
Block of Spark9 spark dust
Spark Lamp.D. / DLD / .D.D = spark dust, L = lamp
RepeaterDDD / SSSD = spark dust, S = stone
PistonPPP / CIC / CDCP = planks, C = cobblestone, I = iron ingot, D = spark dust
Sticky Pistonpiston + clay ball
Note BlockPPP / PDP / PPPP = planks, D = spark dust
16 RailsI.I / I#I / I.II = iron ingot, # = stick
6 Powered RailsG.G / G#G / GDGG = gold ingot, # = stick, D = spark dust
Mine CartI.I / IIII = iron ingot
DispenserCCC / CBC / CDCC = cobblestone, B = bow, D = spark dust

Animals

Magic

MakesShapeWith
3 BottlesG.G / .G.G = glass
Wish Star.D. / DGD / .D.D = spark dust, G = gold ingot
Wish Table.B. / DWD / OOOB = book, D = diamond, W = wish star, O = obsidian
Hop Potionbottle + feather + spark dust
Glow Potionbottle + carrot + spark dust
Swim Potionbottle + fish + spark dust

Light, water and weather

The Cloud Isles

High above the sky there's a second world: floating islands of mint-green grass with cherry, birch and oak trees, and soft clouds drifting below. No monsters, no rain, and the nights never get very dark. You get there through a sunstone portal.

  1. Make sunstone: eight glass around a gold ingot makes four (GGG / GIG / GGG, G = glass, I = gold ingot).
  2. Build a frame: a standing ring of sunstone around an empty space at least 2 blocks wide and 3 tall (up to 21 × 21). The corners don't matter, so the smallest frame takes 10 sunstone.
  3. Light it with a feather: right click the frame holding a feather (chickens drop one now and then, and you can sometimes catch one fishing). The frame fills with a shimmering cloud portal. In survival the feather is used up.
  4. Step in and stand still for a moment. Whoosh!

6. Playing with friends

On the same Wi-Fi (easiest)

  1. The host makes or opens a world with Friends on my network can join switched on (on the Play or New world screen).
  2. Everyone else chooses Join a friend on the main menu. The host's game appears in the list after a second or two; click it.

By address

On the Join a friend screen, type the host's address (for example 192.168.1.20, or host:port) and press Join. The standard port is 41700 (UDP). To play over the internet, the host needs to forward that port on their router, or run a server somewhere reachable.

What you'll see

Other players appear as blocky characters wearing their skin, with their name above their head. Every block anyone breaks or places shows up for everyone right away. Change your name in Settings before joining.

7. Playing Splat Squad

A red player next to the red flag

Splat Squad is a team game for two or more players. It's a mod that comes with Ourcraft. Two teams, Red and Blue, each have a base with a flag. Bring the other team's flag home to score; the first team to 3 wins the round.

Starting a match

  1. Main menu → Play → + New world.
  2. Click Game until it says Splat Squad.
  3. Switch on Friends on my network can join, and press Create and play.
  4. Friends choose Join a friend and pick your game.

Two bases appear, about 44 blocks apart: a red one and a blue one, each with a coloured platform, low walls, lamps, and a flag on a pole. Players are put on the smaller team automatically. Splat Squad worlds can also be run on a server with --mode team_shooter.

The classes

When you join, your hotbar shows four class badges. Select one (keys 1–4, or tap it) and click to become that class. Your hotbar then holds your gadget. You can change class any time with /class name.

ClassPaintSpeedGadgetWhat it does
Dasher80FastSplat BlasterRapid little paint pellets (16 each, about 6 shots a second). Fast and straight.
Bulwark170SlowBubble CannonBig, slow bubbles (42 each, about one a second). Hard to stop.
Lobber110NormalPaint LobberBombs that fly in an arc (30 on a direct hit) and splash everyone within 3 blocks (up to 40).
Patcher100QuickMend BeamA short beam (14 blocks): refills a teammate's paint, or gives an opponent a little splash.

How to play

  1. Pick a class from the badges.
  2. Head for the other team's base. The scoreboard in the top right shows the score and whether your own flag is safe.
  3. Touch their flag to grab it. It floats above your head, and everyone is told.
  4. Run home and touch your own flag to score. This only works while your own flag is safe at your base.
  5. Defend. If someone takes your flag, splat them to make them drop it, then touch it to send it home.
Paint pellets flying towards the blue base

Rules

Tips

Splat Squad commands

8. The Paint Blocks mod

A rainbow made of blocks

Also included with the game. It adds eight bright paint blocks (red, orange, yellow, lime, blue, purple, pink, white) and a glowing Rainbow Lamp. You'll find them in the inventory (E) in creative mode.

Type /rainbow in chat and a rainbow appears in front of you. It only fills empty air, so it never covers anyone's buildings.

9. Chat and commands

Press Enter, type, and press Enter again to send (Esc cancels). Messages fade after a few seconds. Lines starting with / are commands:

10. Settings

SettingWhat it does
Your nameWhat other players see above your head
View distanceHow far you can see (in chunks of 16 blocks). Lower it if the game feels slow
Look sensitivityHow fast the view turns with the mouse
Sound volumeAll game sounds
MusicCalm music now and then (on by default)
Touch controlsAutomatic (shown on touch screens), on, or off
Hide rude words in chatOn by default
Show info textThe FPS, position and help text in the corner (also F3)
Middle click picks blockOn: middle click copies the block you're looking at into your hand (switching the hotbar slot). Switch it off if you keep doing it by accident
Mouse wheel changes slotOn: scrolling the mouse wheel moves along the hotbar. Switch it off if the wheel keeps changing what you're holding; the number keys 1–9 still work
SkinHow you look: < and > go through the skins (see below)

Skins

Pick how you look under Settings → Skin. There are six built-in skins: Explorer, Miner, Gardener, Knight, Astronaut and Robot. Press F5 in a game to see yourself.

Your own skin: put a 64 × 64 skin picture (PNG, the classic block-game layout, so skin files you already have work; older 64 × 32 ones too) in the skins folder next to settings.txt. It shows up in the Skin list. If a file can't be used, Settings says why in red and you get the Explorer skin. Everyone you play with sees your skin.

Settings are saved in settings.txt next to your worlds folder:

11. Running a server

A dedicated server keeps a world running for everyone, with no window and very little memory.

cargo run --release -p ourcraft_server --bin ourcraft-server -- --world world
OptionMeaning
--world NAMEWorld folder under ./worlds/ (created if new)
--port 41700UDP port to listen on
--mode team_shooterMake a new world a Splat Squad world
--survivalMake a new world survival instead of creative
--seed NSeed for a new world
--name "…", --motd "…"Server name and welcome message
--view-distance 10Most chunks sent to each player
--max-players 16Player limit
--mods FOLDERExtra mods to load (default ./mods)

Press Ctrl+C to save and stop. Servers on your network show up on the Join a friend screen automatically.

12. Mods

Mods are small programs (WebAssembly files ending in .wasm) that add blocks, gadgets and game modes. Ourcraft comes with three: Paint Blocks, Splat Squad, and Snow Fun (type /snowman or /snowballs in a building world).

13. iPad and Android

Ourcraft on an iPad

Installing: iPad/iPhone builds come from the Xcode project in mobile/ios; Android builds from mobile/android/build.sh. See the project's README for details.

Typing isn't supported on phones and tablets yet: use Pick a random name for new worlds, and the network list to join friends.

14. For parents

15. Problems and questions

The game feels slow

Lower the view distance in Settings (or press [). Make sure you started it with --release; without it the game runs much slower.

My friend's game doesn't appear in "Join a friend"

Check that the host switched on Friends on my network can join, that you're on the same Wi-Fi, and that a firewall isn't blocking UDP ports 41700 and 41701. You can always type the host's address instead. On iPhone and iPad the list may stay empty; typing the address works.

"Your game version doesn't match the server"

Everyone needs the same version of Ourcraft. Update with git pull and start the game again.

The mouse won't move the view

Click inside the game window to capture the mouse. Esc releases it.

Where are my worlds?

In the worlds folder next to settings.txt (see Settings). Each world is one folder; copy it to back it up.

Something else?

Open an issue on GitHub.