Player Documentation

This page explains how to play and program a robot in Learn From Scraps without reading the project source code.

Core Idea

Each robot has a script. At the start of its turn, the engine executes the entry function my_turn, or one of its localized aliases. Actions called from the script spend action points, move the robot, attack, heal, read the map, or modify terrain.

Minimal example:

my_turn {
  say("Ready")
  move_forward()
  sword_swing()
}

Turn Flow

• The robot starts its turn with available action points.
• Actions run in script order.
• Some actions become more expensive when repeated during the same turn, such as move_forward, move_backward, jump, and dash.
• If an action cannot fully apply, the engine may still spend AP and log a gameplay warning depending on the action.
• Getters such as get_pos_x() or scan_tile(x, y) are not combat actions. They read game state.

Map and Tiles

Maps use short tile codes:

Programming Your Robot

Use my_turn as the entry point:

my_turn {
  if (scan_tile(1, 0) = "enemy") {
    sword_swing()
  } else {
    move_forward()
  }
}

You can define helper functions:

def attack_if_close {
  if (scan_tile(1, 0) = "enemy") {
    sword_swing()
  }
}

my_turn {
  attack_if_close()
}

Reading the Environment

Perception blocks help scripts make decisions:

• get_pos_x() and get_pos_y() return your position.
• scan_tile(x, y) returns empty, ally, enemy, obstacle, or out_of_bounds.
• is_tile_empty(x, y) returns whether a tile can be considered empty.
• get_tile_type(x, y) returns a tile code such as FL or WL.
• get_tile_occupant_type(x, y) returns ally, enemy, unknown_entity, none, obstacle, or out_of_bounds.
• get_tile_occupant_id(x, y) returns the visible occupant id, or an empty string.
• get_entity_x(id), get_entity_y(id), get_entity_health(id), is_entity_alive(id), and get_entity_team(id) read a known entity.

Main Actions

• Movement: move_forward, move_backward, turn, face_north, face_south, face_east, face_west, jump, dash.
• Offense: sword_swing, spear, kick, pistol, grenade, bazooka, lighter, fire_wave, tazer, lazer, ultra_lazer.
• Support: heal, cooling_system, repair_system, say.
• Terrain: place_trap, dig.

Localized Aliases

English action names remain the default examples in this page. The backend also accepts ASCII French and Spanish aliases for player scripts:

• French examples: mon_tour, fonction, repeter, tourner, avancer, reculer, regarder_nord, charger, lancer_grenade, soigner, creuser, dire.
• Spanish examples: mi_turno, funcion, repetir, girar, avanzar, retroceder, mirar_norte, embestir, lanzar_granada, curar, cavar, decir.

The full reference is available in Blocks Reference.

Status Effects

• overheat deals damage over several turns and can be removed with cooling_system().
• short-circuit reduces AP and can be removed with repair_system().

Tips

• Use say("message") to visually debug a strategy.
• Start with short scripts.
• Read the map with getters before taking risky actions.
• Keep enough AP to reposition after an attack.
• Area and projectile actions can affect multiple cells depending on their pattern.

Documentation Joueur

Cette page explique comment jouer et programmer un robot dans Learn From Scraps sans devoir lire le code du projet.

Principe

Chaque robot possede un script. Au debut de son tour, le moteur execute la fonction d'entree my_turn, ou son alias localise mon_tour. Les actions appelees dans ce script consomment des points d'action, modifient la position du robot, attaquent, soignent, lisent la carte ou changent le terrain.

Exemple minimal :

my_turn {
  say("Ready")
  move_forward()
  sword_swing()
}

Tour de jeu

• Le robot commence son tour avec ses points d'action disponibles.
• Les actions sont executees dans l'ordre du script.
• Certaines actions coutent plus cher si elles sont repetees dans le meme tour, par exemple move_forward, move_backward, jump et dash.
• Si une action est impossible, le moteur peut depenser les AP puis journaliser un avertissement de gameplay selon l'action.
• Les getters comme get_pos_x() ou scan_tile(x, y) ne sont pas des actions de combat : ils servent a lire l'etat du jeu.

Carte et tuiles

Les cartes utilisent des codes courts :

Programmer son robot

Utilisez my_turn comme point d'entree :

my_turn {
  if (scan_tile(1, 0) = "enemy") {
    sword_swing()
  } else {
    move_forward()
  }
}

Vous pouvez creer des fonctions :

def attack_if_close {
  if (scan_tile(1, 0) = "enemy") {
    sword_swing()
  }
}

my_turn {
  attack_if_close()
}

Lire l'environnement

Les blocs de perception permettent de prendre des decisions :

• get_pos_x() et get_pos_y() donnent votre position.
• scan_tile(x, y) renvoie empty, ally, enemy, obstacle ou out_of_bounds.
• is_tile_empty(x, y) indique si une tuile peut etre consideree vide.
• get_tile_type(x, y) renvoie le code de tuile comme FL ou WL.
• get_tile_occupant_type(x, y) renvoie ally, enemy, unknown_entity, none, obstacle ou out_of_bounds.
• get_tile_occupant_id(x, y) renvoie l'id visible de l'occupant, ou une chaine vide.
• get_entity_x(id), get_entity_y(id), get_entity_health(id), is_entity_alive(id) et get_entity_team(id) lisent une entite connue.

Actions principales

• Mouvement : move_forward, move_backward, turn, face_north, face_south, face_east, face_west, jump, dash.
• Attaque : sword_swing, spear, kick, pistol, grenade, bazooka, lighter, fire_wave, tazer, lazer, ultra_lazer.
• Support : heal, cooling_system, repair_system, say.
• Terrain : place_trap, dig.

Alias localises

Les exemples historiques de cette page gardent les noms d'action anglais, mais le backend accepte aussi des alias ASCII pour les scripts de joueurs :

• Francais : mon_tour, fonction, repeter, tourner, avancer, reculer, regarder_nord, charger, lancer_grenade, soigner, creuser, dire.
• Espagnol : mi_turno, funcion, repetir, girar, avanzar, retroceder, mirar_norte, embestir, lanzar_granada, curar, cavar, decir.

La reference complete est dans Reference Blocs.

Effets de statut

• overheat inflige des degats pendant plusieurs tours et peut etre retire avec cooling_system().
• short-circuit reduit les AP et peut etre retire avec repair_system().

Conseils

• Utilisez say("message") pour deboguer visuellement une strategie.
• Testez d'abord des scripts courts.
• Lisez la carte avec les getters avant de lancer une action risquee.
• Gardez assez d'AP pour vous repositionner apres une attaque.
• Les actions a zone ou projectile peuvent toucher plusieurs cases selon leur pattern.

Documentacion Jugador

Esta pagina explica como jugar y programar un robot en Learn From Scraps sin leer el codigo fuente del proyecto.

Idea principal

Cada robot tiene un script. Al inicio de su turno, el motor ejecuta la funcion de entrada mi_turno, o uno de sus alias localizados. Las acciones llamadas desde el script gastan puntos de accion, mueven el robot, atacan, curan, leen el mapa o modifican el terreno.

Ejemplo minimo:

funcion mi_turno {
  decir("Listo")
  avanzar()
  golpe_espada()
}

Flujo del turno

• El robot empieza su turno con puntos de accion disponibles.
• Las acciones se ejecutan en el orden del script.
• Algunas acciones cuestan mas si se repiten durante el mismo turno, como avanzar, retroceder, saltar y embestir.
• Si una accion no puede aplicarse por completo, el motor puede gastar AP y registrar una advertencia de gameplay segun la accion.
• Los getters como get_pos_x() o scan_tile(x, y) no son acciones de combate. Sirven para leer el estado del juego.

Mapa y casillas

Los mapas usan codigos cortos:

Programar tu robot

Usa mi_turno como punto de entrada:

funcion mi_turno {
  si (scan_tile(1, 0) = "enemy") {
    golpe_espada()
  } sino {
    avanzar()
  }
}

Puedes crear funciones auxiliares:

funcion atacar_si_cerca {
  si (scan_tile(1, 0) = "enemy") {
    golpe_espada()
  }
}

funcion mi_turno {
  atacar_si_cerca()
}

Leer el entorno

Los bloques de percepcion ayudan a tomar decisiones:

• get_pos_x() y get_pos_y() devuelven tu posicion.
• scan_tile(x, y) devuelve empty, ally, enemy, obstacle o out_of_bounds.
• is_tile_empty(x, y) indica si una casilla puede considerarse vacia.
• get_tile_type(x, y) devuelve un codigo de casilla como FL o WL.
• get_tile_occupant_type(x, y) devuelve ally, enemy, unknown_entity, none, obstacle o out_of_bounds.
• get_tile_occupant_id(x, y) devuelve el id visible del ocupante, o una cadena vacia.
• get_entity_x(id), get_entity_y(id), get_entity_health(id), is_entity_alive(id) y get_entity_team(id) leen una entidad conocida.

Acciones principales

• Movimiento: avanzar, retroceder, girar, mirar_norte, mirar_sur, mirar_este, mirar_oeste, saltar, embestir.
• Ataque: golpe_espada, lanza, patear, pistola, granada, lanzar_granada, bazuca, encendedor, ola_de_fuego, taser, laser, ultra_laser.
• Soporte: curar, sistema_de_enfriamiento, sistema_de_reparacion, decir.
• Terreno: poner_trampa, cavar.

Los nombres de acciones en ingles tambien siguen funcionando. La referencia completa esta disponible en Reference Blocs.

Efectos de estado

• overheat causa dano durante varios turnos y puede retirarse con sistema_de_enfriamiento().
• short-circuit reduce los AP y puede retirarse con sistema_de_reparacion().

Consejos

• Usa decir("mensaje") para depurar visualmente una estrategia.
• Empieza con scripts cortos.
• Lee el mapa con getters antes de tomar acciones arriesgadas.
• Guarda suficientes AP para reposicionarte despues de un ataque.
• Las acciones de area o proyectil pueden afectar varias casillas segun su patron.

LiteralScraps Guide

LiteralScraps is the scripting language executed by the engine. Its current grammar is defined in backend/LFS.Scripting/Grammar/LiteralScraps.g4.

Entry Point

A script must contain exactly one entry function:

my_turn {
  move_forward()
}

Accepted entry aliases:

• my_turn
• mon_tour
• mein_zug
• mi_turno
• minha_vez

Functions

Functions can be declared with def, function, definir, définir, fonction, funktion, funcion, función, or função.

def step_twice {
  move_forward()
  move_forward()
}

my_turn {
  step_twice()
}

Functions can receive parameters:

def speak(message) {
  say(message)
}

my_turn {
  speak("Hello")
}

Variables

A variable is created or replaced with =.

my_turn {
  x = get_pos_x()
  y = get_pos_y()
  say("Position checked")
}

Conditions

Accepted keywords include if, si, wenn and else, sinon, sonst, sino, senão.

my_turn {
  if (scan_tile(1, 0) = "enemy") {
    sword_swing()
  } else {
    move_forward()
  }
}

Loops

repeat repeats a block a fixed number of times.

my_turn {
  repeat(2) {
    move_forward()
  }
}

while repeats while a condition remains true.

my_turn {
  while (get_pos_x() < 3) {
    move_forward()
  }
}

Loop aliases:

• repeat, repeter, répéter, wiederhole, repetir
• while, tantque, solange, mientras, enquanto

Return Values

return, retourne, retour, zurück, devuelve, and retorna return a value.

def enemy_ahead {
  return scan_tile(1, 0) = "enemy"
}

Expressions

LiteralScraps supports:

• integer or decimal numbers
• double-quoted strings
• variables
• function calls
• parentheses
• operations +, -, *, /
• comparisons >, <, =, !=, >=, <=
• boolean logic with & and |

Common Errors

• More than one entry function in the same script.
• Calling an unknown action.
• Calling a getter with the wrong number of arguments.
• Calling say() without a message.
• Calling grenade with one argument: it accepts grenade() or grenade(x, y).
• Using for syntax: the token exists in the grammar, but the current parser does not expose a for statement rule.

Guide LiteralScraps

LiteralScraps est le langage de script execute par le moteur. Sa grammaire actuelle est definie dans backend/LFS.Scripting/Grammar/LiteralScraps.g4.

Point d'entree

Un script doit contenir une seule fonction d'entree :

my_turn {
  move_forward()
}

Aliases d'entree acceptes :

• my_turn
• mon_tour
• mein_zug
• mi_turno
• minha_vez

Fonctions

Les fonctions peuvent etre declarees avec def, function, definir, définir, fonction, funktion, funcion, función ou função.

def step_twice {
  move_forward()
  move_forward()
}

my_turn {
  step_twice()
}

Les fonctions peuvent recevoir des parametres :

def speak(message) {
  say(message)
}

my_turn {
  speak("Hello")
}

Variables

Une variable est creee ou remplacee avec =.

my_turn {
  x = get_pos_x()
  y = get_pos_y()
  say("Position checked")
}

Conditions

Les mots-cles reconnus sont if, si, wenn et else, sinon, sonst, sino, senão.

my_turn {
  if (scan_tile(1, 0) = "enemy") {
    sword_swing()
  } else {
    move_forward()
  }
}

Boucles

repeat repete un bloc un nombre fixe de fois.

my_turn {
  repeat(2) {
    move_forward()
  }
}

while repete tant qu'une condition reste vraie.

my_turn {
  while (get_pos_x() < 3) {
    move_forward()
  }
}

Aliases de boucle :

• repeat, repeter, répéter, wiederhole, repetir
• while, tantque, solange, mientras, enquanto

Retour de fonction

return, retourne, retour, zurück, devuelve et retorna renvoient une valeur.

def enemy_ahead {
  return scan_tile(1, 0) = "enemy"
}

Expressions

LiteralScraps accepte :

• nombres entiers ou decimaux
• chaines entre guillemets doubles
• variables
• appels de fonctions
• parentheses
• operations +, -, *, /
• comparaisons >, <, =, !=, >=, <=
• logique booleenne avec & et |

Erreurs frequentes

• Plus d'une fonction d'entree dans le meme script.
• Appeler une action inconnue.
• Appeler un getter avec le mauvais nombre d'arguments.
• Appeler say() sans message.
• Appeler grenade avec un seul argument : elle accepte grenade() ou grenade(x, y).
• Utiliser une syntaxe for : le token existe dans la grammaire, mais la regle for n'est pas active dans le parser actuel.

Guide LiteralScraps

LiteralScraps es el lenguaje de script ejecutado por el motor. Su gramatica actual esta definida en backend/LFS.Scripting/Grammar/LiteralScraps.g4.

Punto de entrada

Un script debe contener exactamente una funcion de entrada:

mi_turno {
  avanzar()
}

Aliases de entrada aceptados:

• my_turn
• mon_tour
• mein_zug
• mi_turno
• minha_vez

Funciones

Las funciones se pueden declarar con def, function, definir, définir, fonction, funktion, funcion, función o função.

funcion avanzar_dos_veces {
  avanzar()
  avanzar()
}

mi_turno {
  avanzar_dos_veces()
}

Las funciones pueden recibir parametros:

funcion hablar(mensaje) {
  decir(mensaje)
}

mi_turno {
  hablar("Hola")
}

Variables

Una variable se crea o se reemplaza con =.

mi_turno {
  x = get_pos_x()
  y = get_pos_y()
  decir("Posicion revisada")
}

Condiciones

Las palabras clave aceptadas incluyen if, si, wenn y else, sinon, sonst, sino, senão.

mi_turno {
  si (scan_tile(1, 0) = "enemy") {
    golpe_espada()
  } sino {
    avanzar()
  }
}

Bucles

repeat y repetir repiten un bloque un numero fijo de veces.

mi_turno {
  repetir(2) {
    avanzar()
  }
}

while y mientras repiten mientras la condicion sigue siendo verdadera.

mi_turno {
  mientras (get_pos_x() < 3) {
    avanzar()
  }
}

Aliases de bucles:

• repeat, repeter, répéter, wiederhole, repetir
• while, tantque, solange, mientras, enquanto

Valores de retorno

return, retourne, retour, zurück, devuelve y retorna devuelven un valor.

funcion enemigo_delante {
  devuelve scan_tile(1, 0) = "enemy"
}

Expresiones

LiteralScraps soporta:

• numeros enteros o decimales
• cadenas entre comillas dobles
• variables
• llamadas a funciones
• parentesis
• operaciones +, -, *, /
• comparaciones >, <, =, !=, >=, <=
• logica booleana con & y |

Errores comunes

• Mas de una funcion de entrada en el mismo script.
• Llamar a una accion desconocida.
• Llamar a un getter con un numero incorrecto de argumentos.
• Llamar a decir() o say() sin mensaje.
• Llamar a grenade con un argumento: acepta grenade() o grenade(x, y).
• Usar sintaxis for: el token existe en la gramatica, pero el parser actual no expone una regla de sentencia for.

Blocks Reference

This reference describes the blocks currently supported by the backend. It is based on the LiteralScraps grammar, perception builtins, and configs_json/GameConfig.json.

Image placeholders show where visuals can be added later. They are plain text instead of Markdown image links so missing files do not render as broken images.

Language Blocks

Getters and Perception

Movement Actions

Offensive Actions

Support and Terrain

Effects

Important Rules

• Non-throwable actions do not accept target coordinates.
• Throwable actions with the throw-point pattern, currently grenade, accept 0 or 2 arguments.
• Ally damage depends on combatOptions.friendlyFire; self-hit depends on action parameters.
• Getters are logged as information, not as actions.

Reference Blocs

Cette reference decrit les blocs actuellement supportes par le backend. Elle est basee sur la grammaire LiteralScraps, les builtins de perception et configs_json/GameConfig.json.

Les placeholders d'image indiquent ou ajouter les visuels plus tard. Ils ne sont pas des liens Markdown afin d'eviter les images cassees.

Blocs de langage

Getters et perception

Actions de mouvement

Actions offensives

Support et terrain

Effets

Regles importantes

• Les actions non throwable n'acceptent pas de coordonnees cible.
• Les throwables avec pattern throw-point, actuellement grenade, acceptent 0 ou 2 arguments.
• Les degats allies dependent de combatOptions.friendlyFire; l'auto-hit depend des parametres de l'action.
• Les getters sont journalises comme informations, pas comme actions.

Reference Blocs

Esta referencia describe los bloques soportados actualmente por el backend. Esta basada en la gramatica LiteralScraps, los builtins de percepcion y configs_json/GameConfig.json.

Los placeholders de imagen indican donde se pueden anadir visuales mas tarde. Son texto plano en lugar de enlaces Markdown para evitar imagenes rotas si los archivos no existen.

Bloques de lenguaje

Getters y percepcion

Acciones de movimiento

Acciones ofensivas

Soporte y terreno

Efectos

Reglas importantes

• Las acciones que no son throwable no aceptan coordenadas de objetivo.
• Las acciones throwable con el patron throw-point, actualmente grenade, aceptan 0 o 2 argumentos.
• El dano a aliados depende de combatOptions.friendlyFire; el auto-impacto depende de los parametros de la accion.
• Los getters se registran como informacion, no como acciones.