Tronkscript

Tronkscript is a programming language designed for BotBattle. It provides a simple syntax with support for variables, control structures (conditionals and loops), and functions. Tronkscript programs execute from top to bottom, starting with the first statement. The language uses integer-only arithmetic and supports both global and local variable scoping.

Tronkscript is case-sensitive and uses a structured syntax with explicit block endings (e.g., end if, end while, end function). This makes the code more readable and helps prevent common programming errors.

Syntax

Tronkscript uses a straightforward syntax where statements are written one per line. Variables are created implicitly when first assigned a value. The language supports decimal, binary, and hexadecimal number formats.

Variable names must start with a letter or underscore, followed by any combination of letters, digits, or underscores. Examples of valid variable names:

x
my_variable
value123
Value123 -- different variable from value123!
_counter

Tronkscript supports three number formats:

• Decimal: 42, 100, 0
• Binary: 0b1010 (prefix with 0b)
• Hexadecimal: 0x1A (prefix with 0x)

Comments start with double dashes (--) and continue to the end of the line:

-- This is a comment
x = 10  -- This is also a comment

Tronkscript is case-sensitive, meaning myVar and myvar are different variables. Whitespace (spaces and tabs) is generally ignored except where it's needed to separate tokens.

Operators

Tronkscript supports a variety of operators for arithmetic, bitwise operations, and comparisons.

Binary Operators

Binary operators perform operations on two values:

Unary Operators

Unary operators operate on a single value:

Comparison Operators

Comparison operators are used in conditions and return 1 for true, 0 for false:

Variables and Assignments

Variables in Tronkscript are created implicitly when first assigned a value. There is no need to declare variables before using them.

Basic assignment uses the = operator:

x = 10
y = 20
result = x + y

Tronkscript supports compound assignment operators that combine an operation with assignment:

x = 10
x += 5    -- x is now 15 (equivalent to x = x + 5)
x -= 3    -- x is now 12 (equivalent to x = x - 3)
x *= 2    -- x is now 24 (equivalent to x = x * 2)
x /= 4    -- x is now 6 (equivalent to x = x / 4)

Unary operations can also be used in assignments:

x = 10
y = -x    -- y is -10
z = !x    -- z is 0 (because x is not zero)
w = ~x    -- w is bitwise NOT of x

Binary operations combine exactly two values. You cannot chain multiple operations in a single statement:

x = 10
y = 5
sum = x + y        -- 15 (valid: two operands)
diff = x - y       -- 5 (valid: two operands)
prod = x * y       -- 50 (valid: two operands)
quot = x / y       -- 2 (integer division, valid: two operands)
mod = x % y        -- 0 (valid: two operands)
and_result = x & y -- bitwise AND (valid: two operands)
or_result = x | y  -- bitwise OR (valid: two operands)
xor_result = x ^ y -- bitwise XOR (valid: two operands)

temp = a * b
result = temp * c

Control Structures

Conditional Statements

Conditional statements allow your program to execute different code based on conditions. The basic syntax is:

if (x == 10) then
    print(x)
end if

You can add an else clause for when the condition is false:

if (x > 10) then
    print(1)  -- print 1 to indicate "greater"
else
    print(0)  -- print 0 to indicate "not greater"
end if

Multiple conditions can be chained using else if:

if (x > 10) then
    print(1)  -- greater than 10
else if (x == 10) then
    print(0)  -- equal to 10
else
    print(-1)  -- less than 10
end if

While Loops

While loops execute a block of code repeatedly as long as a condition is true:

x = 0
while (x < 10) do
    print(x)
    x = x + 1
end while

The condition is checked before each iteration. If the condition is false initially, the loop body will never execute.

For Loops

For loops iterate over a range of values:

for (i = 0 to 10) do
    print(i)
end for

The loop variable (in this case i) is automatically incremented after each iteration. The loop runs from the start value (inclusive) to the end value (inclusive). If the start value is greater than the end value, the loop body never executes.

You can use variables or numbers for the start and end values:

start = 5
end = 15
for (i = start to end) do
    print(i)
end for

Functions

Functions allow you to organize code into reusable blocks. Functions can take arguments and return values.

Defining Functions

Functions are defined using the function keyword, followed by the function name, parameters in parentheses, and the function body:

function add(a, b) do
    result = a + b
    return result
end function

Functions can take multiple parameters, separated by commas. To compute expressions with multiple operations, you must break them into multiple statements:

function multiply(a, b, c) do
    temp = a * b
    result = temp * c
    return result
end function

Functions can return multiple values. Note that return statements can only contain variables or numbers, not expressions:

function divide_and_mod(a, b) do
    quotient = a / b
    remainder = a % b
    return quotient, remainder
end function

Calling Functions

Functions can be called without capturing return values:

print(42)
my_function(x, y)

Or you can capture return values using assignment:

result = add(5, 3)
-- result is now 8

When a function returns multiple values, you can capture them all:

q, r = divide_and_mod(10, 3)
-- q is 3, r is 1

Functions cannot be defined inside other functions. All functions are defined at the top level of your program and can be called from anywhere.

Execution Model & Tick System

TronkScript is a tick-based interpreter. Each game tick, your bot executes exactly one statement (an assignment, a condition check, a loop check, or a function call). The game then advances to the next tick.

In Tronk, players move once every 10,000 ticks, so your bot has a budget of 10,000 ticks between moves to decide what to do.

What costs a tick?

• Assignments (x = 5, y = x + 1): 1 tick
• Condition checks (if, else if, while condition, for condition): 1 tick
• Function calls: depends on the function (see below)
• Return statements: 1 tick

Function tick costs

Every function has a tick cost. When your bot calls a function, it is paused for that many ticks. For example, calling a game function like turnLeft() costs 100 ticks.

Built-in language functions have the following costs:

User-defined functions cost 1 tick to enter (the function call itself), plus whatever ticks the function body uses.

Coding Style

While Tronkscript doesn't enforce a specific coding style, following these conventions will make your code more readable and maintainable:

• Indentation: Use consistent indentation (spaces or tabs) for nested blocks. This makes it easier to see the structure of your code.
• Naming: Use descriptive variable and function names. Consider using snake_case for multi-word names (e.g., my_variable, calculate_sum).
• Comments: Add comments to explain complex logic or document what your code does. Comments start with --.
• Spacing: Add spaces around operators for readability:x = y + z is clearer than x=y+z.

Example of well-formatted code:

-- Calculate the sum of numbers from 1 to n
function sum_to_n(n) do
    total = 0
    for (i = 1 to n) do
        total = total + i
    end for
    return total
end function

-- Main program
max_value = 10
result = sum_to_n(max_value)
print(result)

Note that in the loop, total = total + i is valid because it uses exactly two operands (total and i). The assignment operator = is separate from the binary + operator.