Your first program

This page takes you from nothing to a computer that drives redstone on its own, one small step at a time. You do not need to know anything about programming: every line is explained. Count about twenty minutes, in a creative world or in survival once you reach the Vacuum Tube Age.

What you will do:

1. get a computer and its storage medium,
2. place it and make it turn, like any Create machine,
3. open its terminal and run a ready-made program,
4. write your own program, line by line,
5. make it blink a lamp, then start by itself.

#1. Get a computer

The first computer of the mod is the Tube Computer, at age III (the Vacuum Tube Age). Every age after it brings a better one: faster, with more memory, a nicer screen and more features. They are all programmed the same way, so everything on this page works on all of them.

Age	Computer
III	Tube Computer
IV	Transistor Mainframe
V	Minicomputer
VI	Personal Computer and Microcontroller
VII	Modern Computer

The page The computers compares them in detail.

In survival, the Tube Computer is made on a Mechanical Crafter: three Tube Logic Modules on top, two Core Memory Planes around a Brass Casing in the middle, two Relays around a Calculating Mechanism at the bottom. JEI shows the recipe and every part. In creative, take one from the creative tab.

A computer keeps its programs on a storage medium, an item you put inside it. The Tube Computer reads a Punch Card Deck: put eight Blank Punch Cards and one string in a crafting table (Blank Punch Cards come from paper cut by a Mechanical Saw, two per sheet). The deck holds 4 KB of programs, plenty for a start.

#2. Place it and make it turn

Place the computer: its screen faces you. Like every Create machine, a computer runs on rotation: bring a turning shaft to its back, from any source (water wheel, windmill, steam engine, or a Creative Motor in creative). The Microcontroller is the exception: it takes its shaft from below.

The rotation speed is the speed of the processor. A computer reaches its full speed at 256 RPM, half of it at 128 RPM, an eighth at 32 RPM. Faster than 256 RPM gives nothing more, and the direction does not matter. A Tube Computer at full speed runs 400 instructions per second, which is a lot for the small programs of this page, but at 8 RPM (a lone water wheel) it only runs about 12: everything takes a while. Gear it up if you can (a large cogwheel driving a small one doubles the speed).

Speed costs power, as everywhere in Create. With the default settings, the Tube Computer asks 16 stress units per RPM: 512 su at 32 RPM, 4,096 su at 256 RPM. Newer computers ask much less. If the network is overstressed, the computer freezes, just as if nothing turned.

#3. Insert the medium

Hold the Punch Card Deck and right-click the computer: the deck goes in. To take it out, sneak and right-click with an empty hand. Your files stay on the deck, so you can carry them to another computer.

#4. Open the terminal

Right-click the computer with an empty hand. The terminal opens and the computer greets you:

Brass OS 1.0
Tier 1 - 2048 cells
Type help to get started.
>

The first line is the name of the system, the second tells the kind of processor (Tier 1 is the Tube Computer) and the size of its memory. The > is the prompt: the computer waits for a command. Type one and press Enter.

#5. Ask for help

Type help:

> help
Commands: help, examples, ls, cd, mkdir,
 cat, edit, run, rm, cp, mv, label, mem,
 id, clear, brass, reboot, shutdown
Libraries: display, fs, link, math, os,
peripheral, rs, string, table, term
New here? 'examples' gives ready-made pr
ograms.
'edit <file>' writes a program, then typ
e its name to run it.
'help <library>' lists its functions (he
lp rs).
Folders: mkdir, cd, 'edit <folder>'. imp
ort "lib" loads another file.

Long lines simply continue on the next line: the paper is 40 characters wide. The commands are the words the prompt understands (all of them are explained in The shell and the editor). The libraries are the toolboxes your programs will use: rs for redstone, math for numbers, term for the screen...

Now type examples. It lists ready-made programs, only those this computer can run:

> examples
hello - your first program
blink - blinks a lamp on top
counter - counts redstone pulses
sequencer - a step sequencer
clock - the time, on a monitor
stock - watches a chest, alarm
speed - drives a speed controller
traffic - a traffic light cycle
buttons - clickable control panel
8 more on a transistor mainframe or newe
r.
'examples <name>' copies it to disk.

#6. Run a ready-made program

Copy the first example onto your deck, then run it by typing its name:

> examples hello
Saved as 'hello'. Read it: edit hello
Run it: hello
> hello
What is your name? Steve
Hello, Steve!
3...
2...
1...
Edit me: edit hello
>

When it asks for your name, type it and press Enter. Congratulations, you just ran a program! The prompt comes back when it ends.

Type ls to list the files of the deck: you will see hello, and how much room is left.

#7. Read it in the editor

Type edit hello. The editor opens, with the program in colour:

-- Your first program. Run it by typing its name: hello
-- print() writes a line, read() waits for what you type.
write("What is your name? ")
local name = read()
print("Hello, " .. name .. "!")
for i = 3, 1, -1 do
  print(i .. "...")
  sleep(1)  -- waits one second
end
print("Edit me: edit hello")

A program is a list of instructions that the computer follows from top to bottom. The lines starting with -- are comments: notes for humans, the computer skips them.

Change something: replace "Hello, " with "Good morning, ". Then:

• Ctrl+S saves the file (the status bar says Saved),
• Esc goes back to the terminal (with unsaved changes, it asks you to press it twice).

Type hello again: the program runs with your change. That is the whole cycle of programming: edit, save, run, and again.

#8. Stop a program

Some programs never end on their own: a factory controller should run forever. To stop the running program, press Ctrl+T in the terminal, or click the Stop button next to the screen. The screen is cleared and shows Terminated, then the prompt comes back.

Try it with this program. Type edit forever: the editor opens on a new, empty file. Type the lines below, save, leave, and run forever:

local tick = 0
while true do
  tick = tick + 1
  print("Still running: " .. tick)
  sleep(1)
end

It counts once a second, forever (while true do repeats until the end of time). Press Ctrl+T to stop it.

#9. Write your own program

Now you write. Type edit factory to create a new file, and type each step below in it (replace the previous content). After each step, save, leave and run factory to see what it does.

#Print text

print("Hello from my factory!")
print("All machines ready.")

Hello from my factory!
All machines ready.

print writes a line on the screen. The text between quotes is a string: the computer shows it as it is.

#Remember values in variables

local item = "iron ingot"
local count = 12
print("Stock: " .. count .. " x " .. item)
count = count + 64
print("After a delivery: " .. count)
print("Full stacks: " .. count // 64)

Stock: 12 x iron ingot
After a delivery: 76
Full stacks: 1

A variable is a name that holds a value. local count = 12 creates the variable count with the value 12; count = count + 64 replaces it with its value plus 64. The two dots .. glue pieces of text together (numbers are turned into text on the way), and // divides and drops the remainder.

#Ask the player something

read() waits until the player types a line in the terminal and presses Enter, and gives back what was typed. write is like print, without going to the next line, so the answer is typed right after the question.

write("What is your name? ")
local name = read()
print("Welcome to the factory, " .. name .. "!")

> factory
What is your name? Steve
Welcome to the factory, Steve!
>

#Make decisions

if runs some lines only when a condition is true. Here, tonumber turns the typed text into a number, or gives nil (nothing) when the text is not a number:

write("How many ingots do you have? ")
local count = tonumber(read())
if count == nil then
  print("That is not a number.")
elseif count >= 64 then
  print("Enough for a full stack!")
else
  print("You need " .. 64 - count .. " more.")
end

> factory
How many ingots do you have? 40
You need 24 more.
> factory
How many ingots do you have? lots
That is not a number.
>

Notice the end: it closes the if. The editor writes it for you when you press Enter after then.

#Repeat with a loop

A for loop repeats lines a number of times. sleep(1) pauses the program for one second (waiting costs no instructions at all):

for i = 1, 5 do
  print("Pressing plate " .. i)
  sleep(1)
end
print("Done!")

Pressing plate 1
Pressing plate 2
Pressing plate 3
Pressing plate 4
Pressing plate 5
Done!

i counts from 1 to 5: the lines between do and end run five times, with i equal to 1, then 2, and so on.

#10. Drive the world: a blinking lamp

Programs become really useful when they act on the world. A computer sends and reads redstone on its six sides: "front" (the screen), "back", "left", "right", "top" and "bottom". Left and right are seen when you stand in front of the screen.

Put a Redstone Lamp on top of the computer. Then edit blink2 and type:

while true do
  rs.set("top", true)   -- lamp on
  sleep(0.5)
  rs.set("top", false)  -- lamp off
  sleep(0.5)
end

Run blink2: the lamp blinks, half a second on, half a second off. rs.set(side, true) sends a full signal (15) out of a side, false cuts it. Press Ctrl+T to stop: when a program is stopped its outputs keep their last value, so the lamp may stay lit until the next program changes it or the computer restarts.

Now make it listen. Put a lever on the left side of the computer, and change the program so that the lamp only blinks while the lever is on:

local on = false
while true do
  if rs.get("left") > 0 then
    on = not on      -- switch: true becomes false, false becomes true
  else
    on = false
  end
  rs.set("top", on)
  sleep(0.5)
end

rs.get("left") reads the redstone power arriving on the left side, from 0 (nothing) to 15. This is the start of real automation: replace the lever with a Create sensor, the lamp with a clutch or a door, and the computer runs a machine. The page Redstone goes much further.

#11. Start by itself: the startup file

A computer runs the file named **startup each time it starts: when it begins to turn, when you press Reboot (Ctrl+R), after Switch on**, and when its chunk is loaded again (after a server restart, for example). Rename your blinker:

> mv blink2 startup
> reboot

The screen clears and the banner comes back, without a prompt this time: startup is running, and the lamp blinks on its own.

Brass OS 1.0
Tier 1 - 2048 cells
Type help to get started.

Your computer is now a real controller: close the terminal and walk away, it keeps working as long as its chunk is loaded and its shaft turns.

#When something goes wrong

The page Error messages explains them one by one.

#Where to go next

• The computers: the six computers, their speed, memory, screens and media, and which one to choose.
• The shell and the editor: every command of the prompt and every shortcut of the editor.
• Brass basics: the language from the start (variables, numbers, text), then control flow and functions.
• Redstone and Events: react to the world without wasting a single instruction.
• Built-in programs: the ready-made programs explained line by line, starting with blink and counter.
• The cookbook: complete projects such as a stock alarm or a password door.