Create: Computing AgesDoc Brass
Référence

Aide-mémoire

Brass sur une page : la syntaxe, chaque fonction des bibliothèques en une ligne, les tournures courantes, les évènements et les touches. Fait pour être imprimé.

Tout d'un coup d'œil, avec un lien vers la page complète de chaque fonction. Imprimez-le (Ctrl+P) et gardez-le à côté du clavier.

Syntaxe

Brass
-- un commentaire jusqu'au bout de la ligne
--[[ un commentaire sur
     plusieurs lignes ]]
local compte = 0                  -- une variable locale (mettez local presque toujours)
vitesse = 128                     -- une variable globale, vue par tous les fichiers
local nom, ouvert = "Mine", true  -- plusieurs d'un coup
local rien = nil                  -- nil : pas de valeur ; seuls nil et false sont faux

-- nombres : 12  3.5  1e3  0xFF     texte : "a"  'b'  [[sur plusieurs lignes]]
local x = 7 // 2 + 7 % 2 + 2 ^ 3  -- 3 + 1 + 8 : division entière, reste, puissance
local ligne = "Stock : " .. compte  -- .. colle du texte (et des nombres)
local taille = #ligne             -- # est la longueur d'un texte ou d'une liste
-- comparer : == ~= (ou !=) < > <= >=      logique : and or not

if compte > 10 then
  print("beaucoup")
elseif compte > 0 then
  print("quelques-uns")
else
  print("aucun")
end

while compte < 3 do compte = compte + 1 end
repeat compte = compte - 1 until compte == 0
for i = 1, 10 do end                      -- 1, 2 ... 10
for i = 10, 1, -2 do end                  -- 10, 8 ... 2
for i, v in ipairs({"a", "b"}) do end     -- une liste, dans l'ordre
for k, v in pairs({x = 1, y = 2}) do end  -- chaque clé d'une table
for v in {"a", "b"} do end                -- les valeurs d'une liste
-- break sort de la boucle

local function aire(l, h)
  return l * h                    -- une fonction renvoie une seule valeur
end
local function coin(l, h)
  return {x = l, y = h}           -- plusieurs valeurs : renvoyer une table
end

local minerais = {"fer", "or"}            -- une liste : minerais[1] vaut "fer"
local pile = {nom = "fer", nombre = 64}   -- un enregistrement : pile.nom, pile["nombre"]
minerais[#minerais + 1] = "cuivre"        -- ajouter à la fin
pile.nombre = nil                         -- retirer une clé

local fort = ("bonjour"):upper()  -- les fonctions de texte marchent comme des méthodes
local r = pcall(aire, 2, 3)       -- r.ok, puis r.value ou r.error

Brass n'est pas Lua (Brass pour les habitués de Lua et ComputerCraft) : une fonction placée dans une fonction ne peut pas utiliser les variables local de celle qui l'entoure (les locales du fichier sont permises) ; return a, b n'existe pas (renvoyez une table) ; pas de ..., pas de métatables, pas de goto ; string.find cherche du texte simple, sans motifs ; pcall renvoie une table ; un texte n'est jamais changé en nombre tout seul ("10" + 1 est une erreur).

Bibliothèques

Les fonctions marquées ⏸ attendent : le programme dort jusqu'à ce qu'elles reviennent. Les coordonnées et les positions commencent à 1.

Fonctions de base

Fonctions globales · tous les ordinateurs

FonctionEffet
print(...)affiche les valeurs, séparées par des tabulations, puis va à la ligne
write(...)affiche sans aller à la ligne
read([masque])⏸ attend une ligne tapée au clavier ; masque la cache ("*")
sleep(secondes)⏸ met le programme en pause (par pas de 1/20 s)
tostring(valeur)n'importe quelle valeur en texte
tonumber(texte [, base])un texte en nombre, ou nil
type(valeur)"nil", "number", "string", "boolean", "table" ou "function"
pairs(t), ipairs(t)parcourt chaque clé, ou t[1], t[2]... jusqu'à nil
error(message)s'arrête sur une erreur
pcall(f, ...)appelle f et attrape ses erreurs : {ok = true, value = ...} ou {ok = false, error = "..."}
assert(valeur [, message])une erreur si valeur vaut false ou nil, sinon la renvoie
import(chemin), require(chemin)exécute un autre fichier une fois et renvoie ce qu'il renvoie

math

math · tous les ordinateurs

FonctionEffet
math.floor(x), math.ceil(x), math.round(x)arrondit vers le bas, vers le haut, au plus proche
math.abs(x)sans son signe
math.min(...), math.max(...)le plus petit, le plus grand
math.sqrt(x), math.exp(x), math.log(x [, base])racine carrée, e puissance x, logarithme
math.sin(x), math.cos(x), math.tan(x)trigonométrie, en radians
math.atan(y [, x]), math.atan2(y, x)angle en radians, atan2 connaît le quart de tour
math.fmod(a, b)reste avec le signe de a (% prend le signe de b)
math.random([m [, n]])hasard : de 0 à 1, de 1 à m, de m à n
math.randomseed(graine)relance la suite aléatoire
math.pi, math.huge3,14159..., l'infini

string

string · tous les ordinateurs · aussi en méthodes : s:upper()

FonctionEffet
string.len(s)longueur (comme #s)
string.sub(s, i [, j])caractères i à j ; un négatif compte depuis la fin
string.upper(s), string.lower(s)majuscules, minuscules
string.rep(s, n [, sep])répété n fois
string.reverse(s)à l'envers
string.byte(s [, i]), string.char(...)code d'un caractère, et l'inverse
string.find(s, texte [, début])position de texte, ou nil (recherche simple)
string.format(fmt, ...)%d %i %f %.2f %s %x %X %% avec largeur : "%5.1f"
string.split(s [, sep])découpe en liste (aux espaces par défaut)
string.trim(s)sans les espaces aux deux bouts
string.starts(s, préfixe), string.ends(s, suffixe)true ou false

table

table · tous les ordinateurs

FonctionEffet
table.insert(t, [pos,] valeur)ajoute à la fin, ou en pos
table.remove(t [, pos])retire et renvoie la dernière valeur, ou celle en pos
table.concat(t [, sep [, i [, j]]])joint les valeurs en un seul texte
table.sort(t [, avant])trie la liste sur place ; avant(a, b) dit si a passe en premier
table.copy(t)une copie simple
table.contains(t, valeur)true si la valeur est dans la table
table.keys(t)la liste des clés

os

os · tous les ordinateurs

FonctionEffet
os.time(), os.clock()ticks, secondes depuis le démarrage de l'ordinateur
os.day_time()heure du jour du monde, de 0 à 23999 (6000 à midi)
os.id(), os.label([nom])numéro de l'ordinateur ; son nom, lu ou changé
os.pull_event([nom])⏸ le prochain évènement (seulement ce nom : les autres sont jetés)
os.queue_event(nom [, données])ajoute un évènement à la file de l'ordinateur lui-même
os.start_timer(secondes)renvoie un numéro ; un évènement timer avec cet id suivra
os.reboot(), os.shutdown()redémarre, éteint
os.tier(), os.memory()génération du processeur (1 à 5) ; {used = , total = } en cellules

term

term · tous les ordinateurs

FonctionEffet
term.clear(), term.clear_line()efface l'écran, la ligne du curseur
term.set_cursor(x, y)déplace le curseur (1, 1 en haut à gauche)
term.get_cursor(), term.get_size(){x = , y = }, {w = , h = }
term.write(texte)écrit au curseur, sans retour à la ligne ni coupure
term.scroll(n)fait monter le texte de n lignes
term.set_fg(couleur), term.set_bg(couleur)couleur du texte et du fond, de 0 à 15
term.colorsterm.colors.red... les 16 couleurs (Couleurs)

gfx

gfx · tous les ordinateurs sauf le Calculateur à tubes · couleurs : de 0 à 15, un nom, ou "none" pour effacer

FonctionEffet
gfx.size(), gfx.clear([couleur]){w = , h = } en pixels ; efface ou remplit le dessin
gfx.pixel(x, y, couleur [, taille]), gfx.get_pixel(x, y)dessine un pixel (un carré) ; en lit un
gfx.line(x1, y1, x2, y2, couleur [, épaisseur])une ligne
gfx.rect(x, y, l, h, couleur [, plein])un rectangle ; plein : true ou l'épaisseur du bord
gfx.circle(x, y, rayon, couleur [, plein])un cercle, ou un disque
gfx.triangle(x1, y1, x2, y2, x3, y3, couleur [, plein])un triangle
gfx.fill(x, y, couleur)pot de peinture
gfx.text(x, y, texte, couleur [, échelle])du texte en police 3 × 5 ; renvoie sa largeur
gfx.image(x, y, lignes [, échelle [, miroir]])un sprite : une couleur hexadécimale par pixel, . pour rien
gfx.scroll(dx, dy [, x, y, l, h])décale le dessin, ou un rectangle du dessin

fs

fs · tous les ordinateurs · chemins : depuis le dossier courant, ou depuis la racine avec /

FonctionEffet
fs.list([dossier])noms des fichiers et des dossiers
fs.exists(chemin), fs.is_dir(chemin)existe ? est-ce un dossier ?
fs.read(chemin)le texte du fichier, ou nil
fs.write(chemin, texte), fs.append(chemin, texte)remplace le fichier, ajoute à sa fin
fs.make_dir(chemin), fs.delete(chemin)crée un dossier ; supprime un fichier ou un dossier
fs.move(depuis, vers), fs.copy(depuis, vers)déplace ou renomme ; copie
fs.size(chemin), fs.free(), fs.capacity()tailles en octets
fs.cwd()le dossier courant : "/" ou "/jeux"

rs, link, display · tous les ordinateurs · faces : front back left right top bottom

FonctionEffet
rs.get(face), rs.get_output(face)redstone qui entre, qui sort : de 0 à 15
rs.set(face, puissance)règle une sortie : de 0 à 15, ou true / false
rs.sides()la liste des six faces
link.set(objet1, objet2, puissance)émet sur une fréquence de Liaison de redstone
link.get(objet1, objet2)puissance reçue sur cette fréquence
display.set(lignes), display.line(n, texte), display.clear()les lignes que lit une Liaison d'affichage

peripheral

peripheral · tous les ordinateurs · noms : une face ("left"), ou type@x,y,z sur un Câble de données

FonctionEffet
peripheral.list([type])noms des blocs que l'ordinateur peut piloter
peripheral.find(type)le premier bloc de ce type, prêt à l'emploi, ou nil
peripheral.type(nom)le type d'un bloc : "inventory", "kinetic"...
peripheral.wrap(nom)une table des méthodes du bloc, ou nil
peripheral.call(nom, méthode, ...)appelle une méthode sans wrap

net

net · Mini-ordinateur et plus récents

FonctionEffet
net.id()l'adresse de cet ordinateur
net.send(id, données [, canal])envoie à un ordinateur ; false s'il est éteint, hors de portée ou saturé (le destinataire doit faire tourner un programme)
net.broadcast(données [, canal])envoie à tous les ordinateurs joignables ; renvoie combien l'ont reçu
net.receive([délai])⏸ le prochain message, ou nil après délai secondes
net.computers(), net.networks()ordinateurs joignables, réseaux Wi-Fi joignables
net.wireless()true si un Modem radio ou un Routeur Wi-Fi est relié

vehicle

vehicle · Micro-ordinateur, Microcontrôleur, Ordinateur moderne

FonctionEffet
vehicle.position(), vehicle.velocity(){x = , y = , z = }, en blocs et en blocs par seconde
vehicle.speed()vitesse en blocs par seconde
vehicle.name(), vehicle.on_vehicle()le nom du véhicule Create Aeronautics (ou nil) ; dessus ou pas ?

Blocs

Les méthodes des tables que renvoient peripheral.wrap et peripheral.find. Chaque bloc a aussi any.type().

Tournures courantes

La boucle principale. Attendre n'importe quel évènement, agir selon son nom, relancer le minuteur à chaque fois qu'il sonne :

Brass
local minuteur = os.start_timer(1)
while true do
  local e = os.pull_event()
  if e.name == "timer" and e.id == minuteur then
    minuteur = os.start_timer(1)  -- chaque seconde : redessiner, lire les capteurs...
  elseif e.name == "redstone" then
    print("gauche : " .. rs.get("left"))
  elseif e.name == "click" then
    print("clic en " .. e.x .. ", " .. e.y)
  elseif e.name == "char" and e.char == "q" then
    break
  end
end

Borner et convertir une valeur. Une puissance redstone (0 à 15) en vitesse (0 à 256 tr/min), sans jamais sortir des bornes :

Brass
local function borner(x, bas, haut)
  return math.max(bas, math.min(haut, x))
end
local trmin = borner(math.floor(rs.get("back") * 256 / 15), 0, 256)

Envelopper un bloc, et vérifier qu'il est là :

Brass
local coffre = peripheral.find("inventory")
if coffre == nil then error("aucun inventaire trouvé") end
print(coffre.count("minecraft:iron_ingot") .. " lingots de fer")

Enregistrer et relire des réglages sous forme de lignes clé=valeur (les valeurs reviennent en texte) :

Brass
local function enregistrer(chemin, reglages)
  local lignes = {}
  for k, v in pairs(reglages) do table.insert(lignes, k .. "=" .. tostring(v)) end
  fs.write(chemin, table.concat(lignes, "\n"))
end

local function relire(chemin)
  local reglages = {}
  local texte = fs.read(chemin)
  if texte == nil then return reglages end
  for ligne in string.split(texte, "\n") do
    local egal = string.find(ligne, "=")
    if egal then reglages[string.sub(ligne, 1, egal - 1)] = string.sub(ligne, egal + 1) end
  end
  return reglages
end

enregistrer("reglages", {cible = 128, mode = "auto"})
print(tonumber(relire("reglages").cible) + 1)
Écran
129

Envoyer et recevoir (Mini-ordinateur et plus récents) :

Brass
-- le dépôt
net.broadcast({objet = "minecraft:iron_ingot", nombre = 64}, "stock")

-- la salle de contrôle
while true do
  local m = net.receive()
  if m.channel == "stock" then print(m.data.objet .. " : " .. m.data.nombre) end
end

Attraper une erreur au lieu de s'arrêter :

Brass
local r = pcall(fs.write, "journal", "plaques : 12")
if not r.ok then print("enregistrement impossible : " .. r.error) end

Évènements

Évènements · local e = os.pull_event(), puis e.name et les champs :

ÉvènementChamps
redstoneaucun : lisez rs.get(face)
timerid
keykey : enter backspace delete up down left right home end tab
charchar : le caractère tapé (lettres, chiffres, espace)
pastetext
click, dragx, y (caractère), px, py (pixel), button (1 gauche, 2 droit, 3 milieu), source ("terminal" ou "monitor")
messagesender, channel, data, via ("cable", "radio", "wifi"), distance
linka, b, power
diskinserted
les vôtresdata

Touches

Clavier

TouchesEffet
Ctrl+Tarrête le programme
Ctrl+Rredémarre l'ordinateur
Ctrl+Vcolle
Échapferme le terminal (le programme continue)
↑ ↓ à l'inviteles commandes précédentes
Tab à l'invitecomplète les commandes et les noms de fichiers
Ctrl+S dans l'éditeurenregistre
Ctrl+Espace dans l'éditeurcomplétion
Ctrl+: dans l'éditeur (AZERTY)commente les lignes

Nombres à retenir

Limites

NombreSens
20 ticksune seconde
256 tr/minpleine vitesse d'un ordinateur
0 à 15puissance redstone
256évènements en attente, minuteurs en attente
200appels imbriqués
65 536caractères dans un texte
32caractères dans un nom de fichier ou un nom d'ordinateur
1 024fichiers et dossiers sur un support
6 × 9pixels dans un caractère