RAG_sources/qa_corpus.md

Straight Code Generation

List reversal

User: Write a MiniScript function to reverse a list.

Assistant:

reverse = function(lst)                                                                                                                      
    result = []                                                                                                                          
    for i in range(lst.len - 1, 0, -1)                                                                                                     
        result.push lst[i]                                                                                                             
    end for                                                                                                                                
    return result                                                                                                                        
end function

Usage:

  print reverse([1, 2, 3, 4, 5])  // [5, 4, 3, 2, 1]

Note the explicit -1 step in range(lst.len - 1, 0, -1) to ensure it returns [] for an empty list rather than counting up.

Letter frequencies

User: Write a MiniScript function to count word frequencies in a string.

Assistant:

wordFreqs = function(s)                                                                                                                      
    freq = {}                                                                                                                              
    for word in s.split                                                                                                                    
        word = word.lower                                                                                                              
        if freq.hasIndex(word) then                                                                                                    
            freq[word] += 1
        else
            freq[word] = 1
        end if
    end for
    return freq
end function

Usage:

result = wordFreqs("The cat sat on the mat the cat")
for kv in result
    print kv.key + ": " + kv.value
end for
// the: 3
// cat: 2
// sat: 1
// on: 1
// mat: 1

A few things to note:

• s.split with no arguments splits on spaces
• word.lower normalizes case so "The" and "the" count together
• hasIndex on a map checks if a key exists

CSV parsing

User: Write a MiniScript function that takes CSV data as a list of strings (one string per line), and returns a list of rows as maps. Assume the first line is headers.

Assistant:

parseCSV = function(lines)                                                                                                                   
    if lines.len < 2 then return []                                                                                                        
    headers = lines.pull.split(",")                                                                                                          
    for i in headers.indexes
        headers[i] = headers[i].trim                                                                                                   
    end for   
    rows = []
    for i in lines.indexes
        fields = lines[i].split(",")
        row = {}
        for j in headers.indexes
            if fields.hasIndex(j) then
                row[headers[j]] = fields[j].trim
            else
                row[headers[j]] = ""
            end if
        end for
        rows.push row
    end for
    return rows
end function

Usage:

data = ["name, age, city", "Alice, 30, Denver", "Bob,25,Portland"]
rows = parseCSV(data)
for row in rows
    print row.name + " from " + row.city + " is " + row.age
end for
// Alice from Denver is 30
// Bob from Portland is 25

Key points:

• lines.pull removes the first element (index 0) from lines and returns it
• .trim strips whitespace around each header and field
• The hasIndex check handles rows with fewer fields than headers, defaulting to ""
• .indexes is an idiomatic way to loop over all indexes of a list or string
• Returned maps support dot notation, so row.name works as long as headers are valid identifiers

Graph BFS

User: Write a MiniScript function to do breadth-first search over a graph.

Assistant:

bfs = function(graph, start, goal)
    queue = [[start, [start]]]  // [node, pathToNode]
    visited = {}
    visited[start] = 1
    while queue.len > 0
        entry = queue.pull
        node = entry[0]
        path = entry[1]
        if node == goal then return path
        if not graph.hasIndex(node) then continue
        for neighbor in graph[node]
            if not visited.hasIndex(neighbor) then
                visited.push neighbor
                newPath = path + [neighbor]
                queue.push [neighbor, newPath]
            end if
        end for
    end while
    return null
end function

Usage:

graph = {}
graph["A"] = ["B", "C"]
graph["B"] = ["A", "D", "E"]
graph["C"] = ["A", "F"]
graph["D"] = ["B"]
graph["E"] = ["B", "F"]
graph["F"] = ["C", "E"]

path = bfs(graph, "A", "F")
print path  // ["A", "C", "F"]

Key points:

• queue.pull removes and returns the first element — used as a FIFO queue
• visited is a map used as a set, adding items with push and checking with hasIndex
• Returns null if no path exists, or the shortest path as a list of nodes

Code Fixing

Index error caused by incorrect use of range

User: The following code generates an error. What's wrong with it?

s = "Hello"
for i in range(0, s.len)
    print s[i]
end for

Assistant: The issue is that range in MiniScript includes the end value. So range(0, s.len) produces [0, 1, 2, 3, 4, 5], and s[5] is out of bounds for a 5-character string (valid indices are 0–4).

Fix:

s = "Hello"
for i in range(0, s.len - 1, 1)
    print s[i]
end for

The explicit step 1 ensures that if s is empty (s.len - 1 == -1), the range returns [] rather than counting down [0, -1].

Or more idiomatically, just iterate the string directly:

s = "Hello"
for ch in s
    print ch
end for

Python-style class syntax

User: Why doesn't this code work?

class Dog:
    def speak(self):
        print "Woof!"
    end function
end class

d = new Dog
d.speak

Assistant: MiniScript uses prototype-based OOP, not class-based like Python. There's no class keyword, no def, and no explicit self parameter. Fix:

Dog = {}                                                                                                                                     
Dog.speak = function
    print "Woof!"                                                                                                                            
end function                                              

d = new Dog
d.speak

Key differences:

• Objects are just maps ({})
• Methods are assigned as properties
• self is automatically available inside methods — don't declare it as a parameter
• new creates an instance with __isa pointing to the prototype

Using elif instead of else if

User: This code gives me a compiler error and I can't figure out why.

x = 15
if x > 20 then
    print "big"
elif x > 10 then
    print "medium"
else
    print "small"
end if

Assistant: The keyword for additional conditions in MiniScript is else if, not elif (that's Python). Fix:

  x = 15                                                                                                                                       
  if x > 20 then
      print "big"                                                                                                                              
  else if x > 10 then                                       
      print "medium"
  else
      print "small"
  end if

Assigning to a global variable without globals

User: Why does this print 0 instead of 5?

count = 0

addToCount = function(n)
    count = count + n
end function

addToCount 5
print count

Assistant: The issue is scoping. Inside the function, count = count + n reads count from the outer scope, but the assignment creates a new local variable called count. The outer count is never modified.

To update the outer variable, use outer or globals:

count = 0

addToCount = function(n)
    outer.count = count + n
end function

addToCount 5
print count

This prints 5. The rule: unqualified assignments always target local scope. Use outer.varName or globals.varName to write to other scopes.

Translation

Binary search (Python)

User: Translate this Python program into MiniScript:

def binary_search(l, value):
    low = 0
    high = len(l)-1
    while low <= high: 
        mid = (low+high)//2
        if l[mid] > value: high = mid-1
        elif l[mid] < value: low = mid+1
        else: return mid
    return -1
myList = list(range(5,25))
print(binary_search(myList, 7)) # 2
print(binary_search(myList, 42)) # -1

Assistant:

binarySearch = function(l, value)
    low = 0
    high = l.len - 1                                                                                                                         
    while low <= high
        mid = floor((low + high) / 2)                                                                                                        
        if l[mid] > value then                            
            high = mid - 1
        else if l[mid] < value then
            low = mid + 1
        else
            return mid
        end if
    end while
    return -1
end function

myList = range(5, 24)
print binarySearch(myList, 7)   // 2
print binarySearch(myList, 42)  // -1

Key changes from Python:

• def → function / end function
• len(l) → l.len (though len(l) would also work, it's less idiomatic)
• // (integer division) → floor(... / 2)
• elif → else if
• range(5,25) → range(5, 24) because MiniScript's range is inclusive on both ends
• No colon after while/if/else — use then after if, and keyword delimiters for blocks

FizzBuzz (Python)

User: Translate the following from Python into MiniScript:

for i in xrange(1, 101):
    if i % 15 == 0:
        print "FizzBuzz"
    elif i % 3 == 0:
        print "Fizz"
    elif i % 5 == 0:
        print "Buzz"
    else:
        print i

Assistant:

for i in range(1, 100)
    if i % 15 == 0 then
        print "FizzBuzz"
    else if i % 3 == 0 then
        print "Fizz"
    else if i % 5 == 0 then
        print "Buzz"
    else
        print i
    end if
end for

Key changes:

• xrange(1, 101) → range(1, 100) — MiniScript range is inclusive
• elif → else if
• Colons removed, then added after if/else if conditions
• Block delimiters end if / end for instead of indentation

LCM (Lua)

User: Translate this program from Lua to MiniScript:

function gcd( m, n )
    while n ~= 0 do
        local q = m
        m = n
        n = q % n
    end
    return m
end

function lcm( m, n )
    return ( m ~= 0 and n ~= 0 ) and m * n / gcd( m, n ) or 0
end

print( lcm(12,18) ) -- 36

Assistant:

gcd = function(m, n)
    while n
        q = m                                                                                                                                
        m = n
        n = q % n                                                                                                                            
    end while                                             
    return m
end function

lcm = function(m, n)
    if m and n then return m * n / gcd(m, n)
    return 0
end function

print lcm(12, 18) // 36

Key changes from Lua:

• function name(...) → name = function(...)/end function
• n ~= 0 → n — nonzero numbers are considered true in MiniScript
• while ... do / end → while / end while
• local keyword not needed — variables are local by default in MiniScript
• Lua's ternary idiom (a and b) and x or y → explicit if statements
• No parentheses needed on print statements
• -- comment marker → // in MiniScript

Function reference (Lua)

User: Convert the following Lua program into MiniScript.

function sayHi ()                                                                                                                            
    print("Hi!")                                                                                                                             
end                                                                                                                                          
                                                                                                                                           
function rep (func, times)                                                                                                                   
    for count = 1, times do                                                                                                                  
        func()                                                                                                                               
    end                                                                                                                                      
end                                                                                                                                          
                                                                                                                                           
rep(sayHi, 4)                                                                                                                                

Assistant:

sayHi = function                                                                                                                             
    print "Hi!"                                                                                                                              
end function                                                                                                                                 
                                                                                                                                           
rep = function(func, times)                                                                                                                  
    for count in range(1, times)                                                                                                             
        func
    end for
end function

rep @sayHi, 4

Key changes from Lua:

• function name(...) / end → name = function(...) / end function
• for count = 1, times do / end → for count in range(1, times) / end for
• func() → func — in MiniScript, bare reference to a function invokes it
• rep(sayHi, 4) → rep @sayHi, 4 — use @ to pass a function reference without invoking it, and no parens needed on a statement-level call

Rot-13 (C#)

User: Convert the following program from C# to MiniScript:

using System;
using System.Linq;

class Program {
    private static char shift(char c) {
        return c.ToString().ToLower().First() switch {
            >= 'a' and <= 'm' => (char)(c + 13),
            >= 'n' and <= 'z' => (char)(c - 13),
            var _ => c
        };
    }

    static string Rot13(string s) => new string(s.Select(c => shift(c)).ToArray());

    static void Main(string[] args) {
        string test = "Hello world!";
        Console.WriteLine(Rot13(test));
    }
}

Assistant:

shift = function(c)
    lower = c.lower
    if lower >= "a" and lower <= "m" then                                                                                                    
        return char(c.code + 13)
    else if lower >= "n" and lower <= "z" then                                                                                               
        return char(c.code - 13)                          
    else
        return c
    end if
end function

rot13 = function(s)
    result = ""
    for c in s
        result += shift(c)
    end for
    return result
end function

test = "Hello world!"
print rot13(test)

Key changes from C#:

• c.ToString().ToLower().First() → c.lower — iterating a string already gives single characters
• (char)(c + 13) → char(c.code + 13) — .code gets the Unicode value, char() converts back
• String comparison works directly in MiniScript ("a" <= "m")
• s.Select(c => shift(c)) → simple for c in s loop building a result string
• No classes, namespaces, or type declarations needed

GCD (Pseudocode)

User: Convert this pseudocode to MiniScript.

function gcd(a, b)
    while b != 0
        t := b
        b := a mod b
        a := t
    return a

Assistant:

gcd = function(a, b)
    while b != 0
        t = b
        b = a % b
        a = t
    end while
    return a
end function

print gcd(48, 18)  // 6

Key translations:

• gcd = function(a, b) rather than function gcd(a, b) — functions are first-class values assigned to variables
• = instead of := for assignment
• % instead of mod for modulo
• end while and end function to close blocks — every while needs a matching end while, and every function needs end function

Recursive GCD (Pseudocode)

User: Convert this pseudocode to MiniScript.

function gcd(a, b)
    if b = 0
        return a
    else
        return gcd(b, a mod b)

Assistant:

gcd = function(a, b)
    if b == 0 then return a
    return gcd(b, a % b)
end function

Key translations from the pseudocode:

• == for equality testing (single = is assignment in MiniScript)
• % instead of mod for modulo
• if/then — MiniScript conditionals require then after the condition; for a single-line if, you can put the result on the same line and skip end if
• No else needed since the if branch returns; the final return only executes when b != 0
• Recursion works directly — gcd(b, a % b) calls the function itself

Binary Search (Pseudocode)

User: Implement the following algorithm in MiniScript.

The inputs are the array, which we call array; the number n of elements in array; and target, the number being searched for. The output is the index in array of target:

1. Let min = 0 and max = n-1.
2. Compute guess as the average of max and min, rounded down (so that it is an integer).
3. If array[guess] equals target, then stop. You found it! Return guess.
4. If the guess was too low, that is, array[guess] < target, then set min = guess + 1.
5. Otherwise, the guess was too high. Set max = guess - 1.
6. Go back to step 2.

Assistant: Here's a direct implementation of that binary search algorithm:

binarySearch = function(array, n, target)
    min = 0
    max = n - 1
    while min <= max
        guess = floor((max + min) / 2)
        if array[guess] == target then return guess
        if array[guess] < target then
            min = guess + 1
        else
            max = guess - 1
        end if
    end while
    return null
end function

The function follows the described steps exactly. floor rounds the average down to an integer (step 2). If the target is found, it returns the index immediately (step 3). If the guess is too low, min is adjusted up (step 4); if too high, max is adjusted down (step 5). The while loop handles step 6 (going back to step 2). It returns null if the target isn't in the array, which happens when min exceeds max.

Example usage:

data = [2, 3, 5, 7, 11, 13, 17, 19, 23]
print binarySearch(data, data.len, 13)   // prints 5
print binarySearch(data, data.len, 4)    // prints null

Explanation

Semiprime

User: Explain what this MiniScript function is doing.

isSemiprime = function(num)
    divisor = 2
    primes = 0
    while primes < 3 and num != 1
        if num % divisor == 0 then
            num = num / divisor
            primes += 1
        else
            divisor = divisor + 1
        end if
    end while
    return primes == 2
end function

Assistant: This function checks whether a number is a semiprime — a number that is the product of exactly two prime factors (e.g., 6 = 2×3, 9 = 3×3, 15 = 3×5).

How it works:

1. Starting with divisor = 2, it tries to divide num by the smallest possible factors
2. Each time divisor divides evenly, it divides num and increments primes (the prime factor count)
3. If divisor doesn't divide evenly, it tries the next one
4. The loop exits early if it finds 3 prime factors (can't be semiprime) or num is fully factored down to 1
5. Returns whether exactly 2 prime factors were found

Example: isSemiprime(15) → divides by 3 (primes=1, num=5), then by 5 (primes=2, num=1) → returns 1 (true).

Levenshtein distance

User: Explain this code:

string.editDistance = function(s2)
    n = self.len
    m = s2.len
    if n == 0 then return m
    if m == 0 then return n
    
    s1chars = self.split("")
    s2chars = s2.split("")
    d = range(0, m)	
    lastCost = 0
    
    for i in range(1, n)
        s1char = s1chars[i-1]
        lastCost = i
        jMinus1 = 0
        for j in range(1, m)
            if s1char == s2chars[jMinus1] then cost = 0 else cost = 1
            
            // set nextCost to the minimum of the following three possibilities:
            a = d[j] + 1
            b = lastCost + 1
            c = cost + d[jMinus1]
            
            if a < b then
                if c < a then nextCost = c else nextCost = a
            else
                if c < b then nextCost = c else nextCost = b
            end if
            
            d[jMinus1] = lastCost
            lastCost = nextCost
            jMinus1 = j
        end for
        d[m] = lastCost
    end for
    
    return nextCost
end function

Assistant: This adds an edit distance (Levenshtein distance) method to the string type. It computes the minimum number of single-character edits (insertions, deletions, or substitutions) needed to transform one string into another.

For example, "kitten".editDistance("sitting") returns 3.

How it works:

This is the classic Wagner-Fischer dynamic programming algorithm, optimized to use a single 1D array d instead of a full 2D matrix.

1. Base cases: If either string is empty, the distance is the length of the other string.
2. Setup: d is initialized to range(0, m) — representing the cost of inserting each character of s2 from nothing.
3. Main loop: For each character i in self (the first string):

• It walks through each character j in s2
• At each step, it computes the minimum cost from three operations:
  • a = d[j] + 1 — deletion (cost from the row above + 1)
  • b = lastCost + 1 — insertion (cost from the left + 1)
  • c = cost + d[jMinus1] — substitution (diagonal cost + 0 if chars match, 1 if not)
• The minimum of a, b, c becomes nextCost
• d is updated in-place as it goes, with lastCost tracking the previous column's value

4. Result: The final nextCost is the edit distance.

MiniScript-specific note: By assigning this to string.editDistance, it becomes a method available on all strings, since string is the prototype for all string values. The string it's called on is accessed via self.

Shoelace formula for polygon area

User: What's going on in this code?

shoelace = function(vertices)
    sum = 0
    points = vertices.len
    
    for i in range(0,points-2)
        sum = sum + vertices[i][0]*vertices[i+1][1]
    end for
    sum = sum + vertices[points-1][0]*vertices[0][1]
    
    for i in range(points-1,1)
        sum = sum - vertices[i][0]*vertices[i-1][1]
    end for
    sum = sum - vertices[0][0]*vertices[points-1][1]
    
    return abs(sum)/2
end function

verts = [[3,4],[5,11],[12,8],[9,5],[5,6]]
print shoelace(verts)

Assistant: This implements the Shoelace formula (also called Gauss's area formula) to calculate the area of a polygon given its vertices.

How it works:

Given a list of 2D vertices like [x, y], the formula computes the area by cross-multiplying coordinates:

1. First loop — sums the "forward" cross products: each vertex's x times the next vertex's y (x₀y₁ + x₁y₂ + x₂y₃ + ...)
2. Wrapping term — adds the last vertex's x times the first vertex's y to close the polygon
3. Second loop — subtracts the "backward" cross products: each vertex's x times the previous vertex's y (x₁y₀ + x₂y₁ + x₃y₂ + ...), going from the last vertex down to index 1
4. Wrapping term — subtracts the first vertex's x times the last vertex's y
5. Result — abs(sum) / 2 gives the polygon's area (the abs ensures a positive result regardless of vertex winding order)

For the given pentagon with vertices [3,4], [5,11], [12,8], [9,5], [5,6], it prints 30.

Note: There's a subtle bug risk — the second loop uses range(points-1, 1). Since MiniScript's range auto-descends, this correctly counts down. But if there were fewer than 2 vertices, it could behave unexpectedly.

API/Documentation Questions

Map iteration

User: How do I iterate over a map in MiniScript?

Assistant: In MiniScript, iterate over a map using a for loop:

m = {"a": 1, "b": 2, "c": 3}
for kv in m print kv.key + ": " + kv.value
end for

The loop variable (kv in this example) is a mini-map with .key and .value properties for each entry.

Repeating n times

User: How do I repeat some code n times?

Assistant: You can use a for loop with a range from 1 to n:

for i in range(1, n, 1):
    print "Iteration " + i
end for

Alterantively, if you want to start counting at zero, you could use range(0, n-1, 1).

The explicit step 1 (third parameter to range) ensures that it always counts up or returns an empty list; without it, range(1, n) would return [1, 0] when n is 0.

Style & Idioms

Dice-rolling example

User: How can I make the following MiniScript code more idiomatic?

rollDice = function(diceStr)
    // parse the string
    result = 0;
    modifier = 0;
    plusPos = diceStr.indexOf("+");
    minusPos = diceStr.indexOf("-");
    if (plusPos != null) then
        modifier = (diceStr[(plusPos + 1):]).val;
        diceStr = (diceStr[:plusPos]);
    else if (minusPos != null) then
        modifier = -(diceStr[(minusPos + 1):]).val;
        diceStr = (diceStr[:(minusPos)]);
    end if
    dPos = diceStr.indexOf("d");
    if (dPos == null) then
        return(null);
    end if
    numDice = (diceStr[:(dPos)]).val;
    numSides = (diceStr[(dPos + 1):]).val;
    if (numDice == 0 or numSides == 0) then
        return(null);
    end if
    result = {};
    result["rolls"] = [];
    result["total"] = modifier;
    for i in range(0, (numDice - 1))
        roll = floor(rnd * numSides) + 1;
        result["rolls"].push(roll);
        result["total"] = result["total"] + roll
    end for
    return(result);
end function

print(rollDice("3d6+1"));

Assistant: Here is a cleaned-up version:

rollDice = function(diceStr)
    modifier = 0
    plusPos = diceStr.indexOf("+")
    minusPos = diceStr.indexOf("-")
    if plusPos != null then
        modifier = diceStr[plusPos+1:].val
        diceStr = diceStr[:plusPos]
    else if minusPos != null then
        modifier = -diceStr[minusPos+1:].val
        diceStr = diceStr[:minusPos]
    end if
    dPos = diceStr.indexOf("d")
    if dPos == null then return null
    numDice = diceStr[:dPos].val
    numSides = diceStr[dPos+1:].val
    if numDice == 0 or numSides == 0 then return null
    result = {}
    result.rolls = []
    result.total = modifier
    for i in range(1, numDice)
        roll = ceil(rnd * numSides)
        result.rolls.push roll
        result.total += roll
    end for
    return result
end function

print rollDice("3d6+1")

Summary of changes:

• Removed semicolons — they're used only to separate multiple statements on a line, and are unnecessary noise at the end of a line
• Removed parentheses from if conditions, return, print, and .push — parentheses aren't needed on statement-level calls or conditionals
• Removed redundant parentheses around slice expressions like (diceStr[(plusPos + 1):]) → diceStr[plusPos+1:]
• Dot notation for map keys: result.rolls instead of result["rolls"]
• range(1, numDice) - more readable/idiomatic, and doesn't affect the behavior since the loop variable isn't used
• Removed unused result = 0 at the top (it was immediately overwritten)

Questions from Learn to Code in 30 Days

Variables and assignment

User: How do variables work in MiniScript? Do I need to declare them with a type?

Assistant: Here's a quick example showing global and local variables:

demo = function
    g = "local value"       // creates a NEW local g
    print g                 // local value
    print globals.g         // global value
    globals.g = "changed"
end function

g = "global value"
demo
print g                     // changed

There are six data types in MiniScript: number, string, list, map, function, and null. You can check a value's type at runtime if needed:

x = 3.14
if x isa number then print "It's a number!"

In short, there are no type declarations, no var or let keywords, and no type annotations. Just pick a name and assign a value.

Updating a variable with its own value

User: How do I increment a variable or add to its existing value in MiniScript?

Assistant: MiniScript supports compound assignment operators, so you don't need to write out the variable name twice. You can use += to add to an existing value, along with similar operators for other arithmetic operations.

x = 10
x += 1       // x is now 11
x += 5       // x is now 16
x -= 3       // x is now 13
x *= 2       // x is now 26
x /= 4       // x is now 6.5

The += operator also works with strings for concatenation:

greeting = "Hello"
greeting += ", world!"
print greeting   // Hello, world!

And it works with lists using push behavior when combined with +:

myList = [1, 2, 3]
myList += [4, 5]
print myList   // [1, 2, 3, 4, 5]

The long form x = x + 1 also works, but x += 1 is preferred as it is cleaner and more idiomatic. Note that there are no ++ or -- operators in MiniScript; use x += 1 and x -= 1 instead.

Comments in MiniScript

User: How do I add comments to my MiniScript code?

Assistant: MiniScript uses // for comments. Everything from // to the end of the line is ignored by the compiler. There is no block comment syntax (like /* */ in some other languages), so each comment line needs its own //.

Here are some examples:

// This is a full-line comment

x = 42  // This is an inline comment after a statement

// You can use comments to explain logic:
// Calculate the area of a circle
radius = 5
area = pi * radius ^ 2
print "Area: " + area

// Comments are handy for temporarily disabling code:
// print "This line won't run"

Since there are no multi-line block comments, if you need to comment out a larger section, just put // at the start of each line:

// This function is not ready yet:
// myFunc = function(x)
//     return x * 2
// end function

Getting user input

User: How do I get input from the user in MiniScript?

Assistant: In most MiniScript environments, you can use the input function to prompt the user and get a string back:

name = input("What is your name? ")
print "Hello, " + name + "!"

The input function takes an optional prompt string, displays it, waits for the user to type a line and press Enter, and returns what they typed as a string.

If you need a number from the user, convert the result with val:

s = input("Enter a number: ")
n = s.val
print "Double that is: " + n * 2

If the user types something that isn't a valid number, val returns 0. You can check for this if needed:

s = input("Enter a number: ")
if s.val == 0 and s != "0" then
    print "That's not a valid number."
else
    print "You entered: " + s.val
end if

Calling input with no argument works too — it just waits for input without displaying a prompt.

Converting strings to numbers with val

User: I'm trying to add a number the user typed in, but MiniScript is concatenating strings instead of adding. What's going on?

Assistant: The input function in MiniScript always returns a string. So when you use the + operator on two strings, it concatenates them rather than adding them as numbers. You need to convert the input to a number using the val function.

Here is the problem in action:

x = input("Enter a number: ")
print x + 10

If you type 5, this prints 510 because x is the string "5", and "5" + 10 concatenates them.

The fix is to use val to convert the string to a number:

x = input("Enter a number: ").val
print x + 10

Now if you type 5, this correctly prints 15.

You can also convert after the fact:

x = input("Enter a number: ")
print x.val + 10

The val function parses a string and returns its numeric value. If the string is not a valid number, val returns 0. This is the standard way to handle numeric user input in MiniScript.

Comparison operators and boolean values

User: How do I compare numbers or strings in MiniScript?

Assistant: MiniScript supports six comparison operators:

• == (equal)
• != (not equal)
• < (less than)
• > (greater than)
• <= (less than or equal)
• >= (greater than or equal)

These work on numbers, strings (compared alphabetically), and lists.

print 5 > 3       // 1 (true)
print 5 == 5      // 1 (true)
print 5 != 3      // 1 (true)
print "apple" < "banana"  // 1 (true, alphabetical order)

MiniScript has no separate boolean type. Instead, it uses numbers: 1 means true and 0 means false. The keywords true and false are just shortcuts for 1 and 0:

print true       // 1
print false      // 0
print true == 1  // 1

You can combine comparisons with the logical operators and, or, and not:

x = 15
print x > 10 and x < 20  // 1 (true: x is between 10 and 20)
print x < 5 or x > 100   // 0 (false: neither condition is met)
print not (x == 15)       // 0 (false: x is 15, negated)

It's also possible to chain several comparisons in a row, in which case, each pair of operands is considered in turn. This is often used for checking whether a number is within a civen range:

x = 15
print 10 <= x <= 20    // 1 (true: x is between 10 and 20, inclusive)

Since any nonzero number counts as true and zero counts as false, you can use numbers directly in conditions:

lives = 3
if lives then print "Still playing!"   // prints, because 3 is truthy
lives = 0
if not lives then print "Game over!"   // prints, because 0 is falsy

One thing to watch out for: null is not the same as 0. A comparison like null == 0 evaluates to 0 (false), and using null in a boolean context is falsy, but it's not a number.

While loops

User: How do I write a while loop in MiniScript?

Assistant: A while loop in MiniScript repeats a block of code as long as a condition is true. The basic structure is:

while condition
    // code to repeat
end while

Here's a simple example that counts from 1 to 5:

i = 1
while i <= 5
    print i
    i += 1
end while
// 1
// 2
// 3
// 4
// 5

You can use break to exit the loop early, and continue to skip to the next iteration:

i = 0
while i < 10
    i += 1
    if i % 2 == 0 then continue
    if i > 7 then break
    print i
end while
// 1
// 3
// 5
// 7

A while true loop runs forever until explicitly broken out of, which is useful for input loops or game loops:

while true
    line = input("Enter a number (0 to quit): ")
    n = line.val
    if n == 0 then break
    print n + " squared is " + n^2
end while

Key points:

• The condition is checked before each iteration, so the body may execute zero times
• There are no parentheses around the condition (unlike C or Java)
• The block must be closed with end while
• break and continue work as you'd expect from other languages

For loops and range

User: How do I write a for loop in MiniScript?

Assistant: A for loop in MiniScript iterates over a collection (list, string, or map), by assigning a loop variable to each element of the collection in turn.

Iterating over a list:

fruits = ["apple", "banana", "cherry"]
for fruit in fruits
    print fruit
end for

This prints each element in the list. You can also iterate over a string (getting each character), or over a map (getting key-value pairs).

Iterating over a map:

ages = {"Alice": 30, "Bob": 25}
for kv in ages
    print kv.key + " is " + kv.value
end for

When iterating over a map, each iteration variable is a mini-map with .key and .value properties.

Using range for numeric loops:

The range function generates a list of numbers. It takes up to three arguments: range(start, end, step), and is very commonly used with for.

for i in range(1, 5)
    print i
end for
// prints 1, 2, 3, 4, 5

Important: unlike Python, range in MiniScript is inclusive of the end value. So range(1, 5) gives [1, 2, 3, 4, 5], not [1, 2, 3, 4].

With a step value:

for i in range(0, 10, 2)
    print i
end for
// prints 0, 2, 4, 6, 8, 10

Counting down:

range auto-descends when the start is greater than the end:

for i in range(5, 1)
    print i
end for
// prints 5, 4, 3, 2, 1

However, when using computed bounds, it is best practice to include an explicit step to avoid surprises. For example, range(0, n-1) when n is 0 would produce [0, -1] instead of an empty list. Use range(0, n-1, 1) to ensure it returns [] when n is 0. Similarly, when counting down use range(n-1, 0, -1).

With just one argument:

range with a single argument counts from 0 up to that value:

for i in range(3)
    print i
end for
// prints 0, 1, 2, 3

Note again that this is inclusive, so range(3) gives four values: 0, 1, 2, and 3.

range

User: How does range work in MiniScript?

Assistant: The range function generates a list of numbers. It can take one, two, or three arguments: range(end), range(start, end), or range(start, end, step).

Two-argument form — inclusive end:

Unlike Python, MiniScript's range includes the end value:

print range(1, 5)   // [1, 2, 3, 4, 5]

Single-argument form:

With one argument, range counts from 0 up to (and including) that value:

print range(3)   // [0, 1, 2, 3]

Note this produces four values, not three.

Auto-descending behavior:

When the start value is greater than the end value, range automatically counts down:

print range(5, 1)   // [5, 4, 3, 2, 1]

Explicit step parameter:

The optional third argument sets the step size:

print range(0, 10, 2)    // [0, 2, 4, 6, 8, 10]
print range(10, 0, -2)   // [10, 8, 6, 4, 2, 0]

Common pitfall — auto-descend with computed bounds:

The auto-descending behavior can cause bugs when bounds are computed. Consider range(0, n-1) intended to count from 0 up to the last index. When n is 0, this becomes range(0, -1), which auto-descends and returns [0, -1] instead of an empty list. The fix is to include an explicit step:

// Bad — returns [0, -1] when n is 0:
print range(0, n - 1)

// Good — returns [] when n is 0:
print range(0, n - 1, 1)

Similarly, when counting down with computed bounds, use an explicit step of -1 to avoid accidentally counting up:

range(n - 1, 0, -1)

As a rule of thumb: whenever either bound is a computed value, include an explicit step.

Nested loops

User: Can I nest loops inside each other in MiniScript? Can you show me an example?

Assistant: Yes, you can absolutely nest loops inside each other in MiniScript. There is no limit to how deeply you can nest them, and you can mix loop types freely (e.g., a for loop inside a while loop, or vice versa).

Here is an example that prints a multiplication table using nested for loops:

for row in range(1, 5)
    line = ""
    for col in range(1, 5)
        product = row * col
        line += str(product) + char(9)  // char(9) is tab
    end for
    print line
end for

Output:

1	2	3	4	5
2	4	6	8	10
3	6	9	12	15
4	8	12	16	20
5	10	15	20	25

You can also nest different loop types. Here is an example that uses a for loop with a while loop inside it:

for word in ["cat", "do", "be"]
    result = word
    while result.len < 6
        result += word
    end while
    print result
end for

Output:

catcat
dododo
bebebe

Each inner loop runs to completion for every single iteration of the outer loop. The break and continue keywords apply only to the innermost loop they appear in, so you can control each loop independently.

If/then/else

User: How do I write conditional statements in MiniScript?

Assistant: MiniScript uses if/then/else if/else/end if for conditional statements.

Basic if/then:

x = 10
if x > 5 then print "x is big"

When the body is short, you can put it on the same line after then.

Multi-line if block:

x = 10
if x > 5 then
    print "x is greater than 5"
    print "that's pretty big"
end if

When the body is more than one statement, put it on subsequent lines and close the block with end if.

if/else:

age = 15
if age >= 18 then
    print "You can vote."
else
    print "Too young to vote."
end if

if/else if/else:

score = 85
if score >= 90 then
    grade = "A"
else if score >= 80 then
    grade = "B"
else if score >= 70 then
    grade = "C"
else
    grade = "F"
end if
print "Your grade: " + grade

Note that it's else if (two words), not elseif or elif.

Single-line form:

x = 42
if x > 0 then print "positive" else print "non-positive"

This works for simple cases where each branch is just one statement.

Conditions use standard comparison operators (==, !=, <, >, <=, >=) and can be combined with and, or, and not:

temp = 72
humid = 40
if temp > 60 and temp < 80 and humid < 60 then
    print "Nice weather!"
end if

A few things to note:

• MiniScript has no separate boolean type; true is just 1 and false is 0
• Any nonzero number is truthy; 0, "" (empty string), and null are falsy
• Parentheses around the condition are not needed (and are discouraged)

Single-line if statements

User: Can I put an if statement on a single line in MiniScript?

Assistant: Yes! MiniScript supports single-line if statements. Just put the then clause on the same line as the if, and skip the end if:

x = 10
if x > 5 then print "big"

You can also include an else on the same line:

if x > 5 then print "big" else print "small"

This works for any single statement after then (and after else). You only need end if when the body spans multiple lines:

// Multi-line form (needs end if)
if x > 5 then
    print "big"
    print "very big indeed"
end if

The single-line form is handy for quick guards and early returns:

myFunc = function(n)
    if n == null then return 0
    return n * 2
end function

The key rule is: if the statement after then is on the same line, no end if is needed. If it's on the next line, you must close the block with end if.

break and continue

User: How do I exit a loop early, or skip to the next iteration in MiniScript?

Assistant: MiniScript supports both break and continue for controlling loop execution.

Use break to exit a loop early:

for i in range(1, 100)
    if i > 5 then break
    print i
end for
// prints 1 through 5, then exits the loop

Use continue to skip the rest of the current iteration and move on to the next one:

for i in range(1, 10)
    if i % 2 == 0 then continue
    print i
end for
// prints only odd numbers: 1, 3, 5, 7, 9

Both work with while loops too:

while true
    line = input("Enter something (or 'quit'): ")
    if line == "quit" then break
    if line == "" then continue
    print "You said: " + line
end while

Note that break and continue apply to the innermost loop only. If you have nested loops and need to exit an outer loop, you can set a flag variable and check it after the inner loop:

done = false
for row in range(0, 9)
    for col in range(0, 9)
        if grid[row][col] == target then
            print "Found at " + row + "," + col
            done = true
            break
        end if
    end for
    if done then break
end for

Creating and accessing lists

User: How do I create a list or array in MiniScript?

Assistant: In MiniScript, you create a list using square brackets, and access elements by index (0-based). Negative indices count from the end.

// Create a list
myList = [10, 20, 30, 40, 50]

// Access elements by index
print myList[0]    // 10 (first element)
print myList[2]    // 30 (third element)
print myList[-1]   // 50 (last element)
print myList[-2]   // 40 (second to last)

You can also create an empty list and add elements to it:

myList = []
myList.push "apple"
myList.push "banana"
myList.push "cherry"
print myList        // ["apple", "banana", "cherry"]
print myList[1]     // banana

Lists support slicing to get a sublist:

nums = [10, 20, 30, 40, 50]
print nums[1:3]    // [20, 30] (index 1 up to but not including 3)
print nums[2:]     // [30, 40, 50] (from index 2 to end)
print nums[:3]     // [10, 20, 30] (from start up to index 3)
print nums[-2:]    // [40, 50] (last 2 elements)

Lists can hold any mix of types, including other lists:

mixed = [1, "hello", [2, 3], null]
print mixed[1]       // hello
print mixed[2][0]    // 2

Useful list methods include len to get the size, indexOf to find an element, and hasIndex to check whether an index is valid:

colors = ["red", "green", "blue"]
print colors.len           // 3
print colors.indexOf("green")  // 1
print colors.hasIndex(5)   // 0 (false)

Negative indexing

User: What does a negative index do on a list or string in MiniScript?

Assistant: In MiniScript, a negative index counts backward from the end of a list or string. Index -1 refers to the last element, -2 to the second-to-last, and so on. This works for both single-element access and slicing.

With lists:

myList = ["a", "b", "c", "d", "e"]
print myList[-1]    // e
print myList[-2]    // d
print myList[-3:]   // ["c", "d", "e"]  (last 3 elements)
print myList[1:-1]  // ["b", "c", "d"]  (from index 1 up to but not including the last)

With strings:

s = "Hello"
print s[-1]     // o
print s[-2]     // l
print s[-3:]    // llo  (last 3 characters)
print s[1:-1]   // ell  (from index 1 up to but not including the last)

This is a convenient way to access the end of a sequence without needing to know its length. Instead of writing myList[myList.len - 1], you can simply write myList[-1].

User: How do I count backwards into a list or string in MiniScript?

Assistant: Use negative indices to count backwards from the end. Index -1 refers to the last element, -2 to the second-to-last, and so on.

For lists:

nums = [10, 20, 30, 40, 50]
print nums[-1]   // 50 (last element)
print nums[-2]   // 40 (second to last)
print nums[-3]   // 30

For strings:

s = "Hello"
print s[-1]      // "o" (last character)
print s[-2]      // "l"

Negative indices also work with slicing:

nums = [10, 20, 30, 40, 50]
print nums[-3:]    // [30, 40, 50] (last 3 elements)
print nums[-3:-1]  // [30, 40] (from third-to-last up to but not including last)

s = "Hello"
print s[-3:]       // "llo" (last 3 characters)

Any place you use a positive index, you can substitute a negative one to count from the end instead.

List methods: push, pop, pull, insert, remove

User: What methods are available for adding and removing elements from a list in MiniScript?

Assistant: MiniScript provides several methods for adding and removing elements from a list:

Adding elements:

• push — adds an element to the end of the list
• insert — inserts an element at a specific index position

myList = [1, 2, 3]

myList.push 4
print myList    // [1, 2, 3, 4]

myList.insert 0, "first"
print myList    // ["first", 1, 2, 3, 4]

myList.insert 2, "middle"
print myList    // ["first", 1, "middle", 2, 3, 4]

You can also use the + operator to concatenate two lists, which returns a new list rather than modifying the original:

a = [1, 2]
b = [3, 4]
c = a + b
print c    // [1, 2, 3, 4]

Removing elements:

• pop — removes and returns the last element
• pull — removes and returns the first element
• remove — removes the element at a specific index

myList = ["a", "b", "c", "d", "e"]

last = myList.pop
print last      // e
print myList    // ["a", "b", "c", "d"]

first = myList.pull
print first     // a
print myList    // ["b", "c", "d"]

myList.remove 1
print myList    // ["b", "d"]

Note that remove takes an index, not a value. To remove by value, first find the index with indexOf:

myList = ["apple", "banana", "cherry"]
idx = myList.indexOf("banana")
if idx != null then myList.remove idx
print myList    // ["apple", "cherry"]

Immutable strings

User: How do I modify a string in MiniScript?

Assistant: Strings in MiniScript are immutable value types. You cannot change a character in place — any "modification" actually creates a new string. Here are the main techniques.

Using replace:

s = "Hello World"
s = s.replace("World", "MiniScript")
print s  // Hello MiniScript

Using slicing and concatenation:

s = "Hello!"
// Change character at index 2 from "l" to "L"
s = s[:2] + "L" + s[3:]
print s  // HeLlo!

Using remove and insert:

s = "cat"
s = s.remove("a")
print s  // ct

s = "Hllo"
s = s.insert(1, "e")
print s  // Hello

Building up a string piece by piece:

result = ""
for ch in "Hello"
    if ch == "l" then result += "r" else result += ch
end for
print result  // Herro

The key concept is that none of these operations change the original string. Each one produces a new string, which you then assign back to the variable (or to a different variable).

Slicing lists and strings

User: How does slicing work in MiniScript?

Assistant: Slicing extracts a portion of a list or string using the syntax value[start:end], where start is the first index included and end is the first index excluded (i.e., the end index is exclusive, just like Python).

Basic slicing:

myList = ["a", "b", "c", "d", "e"]
print myList[1:3]   // ["b", "c"]

s = "Hello World"
print s[0:5]        // Hello

Omitting start or end:

You can omit the start index to slice from the beginning, or omit the end index to slice to the end:

myList = [10, 20, 30, 40, 50]
print myList[:3]    // [10, 20, 30]
print myList[2:]    // [30, 40, 50]

s = "Hello"
print s[:3]         // Hel
print s[3:]         // lo

Negative indices in slices:

Negative indices count from the end, where -1 is the last element:

myList = [10, 20, 30, 40, 50]
print myList[-3:]   // [30, 40, 50]
print myList[:-1]   // [10, 20, 30, 40]

s = "Hello"
print s[-3:]        // llo

Making a shallow copy:

Omit both start and end to get a shallow copy of a list:

original = [1, 2, 3]
copy = original[:]
copy.push 4
print original      // [1, 2, 3]
print copy          // [1, 2, 3, 4]

This works on strings too, though since strings are value types in MiniScript, copying them is less of a concern.

Key points:

• The start index is inclusive; the end index is exclusive
• Omit the start to slice from the beginning; omit the end to slice through the end
• Negative indices count from the end
• [:] creates a shallow copy of a list
• Slicing works the same way on both lists and strings

Substrings

User: How do I get a substring of a larger string?

Assistant: Use the slice syntax s[start:end] to extract a substring. The start index is inclusive and the end index is exclusive (i.e., the character at end is not included).

Basic substring extraction:

s = "Hello, World!"
print s[0:5]        // Hello
print s[7:12]       // World

Omitting start or end:

Leave out the start index to begin from the start of the string, or leave out the end index to go through the end:

s = "Hello, World!"
print s[:5]         // Hello
print s[7:]         // World!

Negative indices:

Negative indices count from the end of the string, where -1 is the last character:

s = "Hello, World!"
print s[-6:]        // orld!
print s[-6:-1]      // orld
print s[:-1]        // Hello, World

Getting a single character:

Use a single index (no colon) to get one character:

s = "Hello"
print s[0]          // H
print s[-1]         // o

Practical examples:

// Get a file extension
filename = "photo.png"
dotPos = filename.indexOf(".")
ext = filename[dotPos + 1:]
print ext           // png

// Get the first N characters
s = "MiniScript is fun"
print s[:10]        // MiniScript

// Get the last 3 characters
s = "abcdef"
print s[-3:]        // def

// Extract a middle portion
line = "Name: Alice Smith"
print line[6:]      // Alice Smith

Note that strings in MiniScript are value types, so slicing always produces a new string without affecting the original.

Sublists

User: How do I get a portion of a list, like just the first three elements?

Assistant: Use the slice syntax list[start:end], where start is the index of the first element you want, and end is the index just past the last element you want. Both are optional.

To get the first three elements:

myList = ["a", "b", "c", "d", "e"]
print myList[:3]   // ["a", "b", "c"]

When you omit start, it defaults to 0 (the beginning). When you omit end, it defaults to the end of the list:

myList = [10, 20, 30, 40, 50]

print myList[1:3]   // [20, 30] — elements at index 1 and 2
print myList[:2]    // [10, 20] — first two elements
print myList[3:]    // [40, 50] — from index 3 to the end
print myList[:]     // [10, 20, 30, 40, 50] — shallow copy of the whole list

You can also use negative indices, which count from the end:

myList = ["a", "b", "c", "d", "e"]

print myList[-3:]    // ["c", "d", "e"] — last three elements
print myList[-2:]    // ["d", "e"] — last two elements
print myList[:-1]    // ["a", "b", "c", "d"] — everything except the last

A slice always returns a new list, so modifying the slice won't affect the original. This makes myList[:] a handy way to make a shallow copy of a list.

Reference types vs value types (lists)

User: I assigned a list to a new variable and changed the new variable, but the original list changed too. Why?

Assistant: In MiniScript, lists and maps are reference types. When you assign a list to a new variable, you are not making a copy — both variables point to the same list in memory. So any change through one variable is visible through the other.

a = [1, 2, 3]
b = a           // b points to the SAME list as a
b.push 4
print a         // [1, 2, 3, 4]  -- a changed too!

To make an independent copy, use the slice operator [:]:

a = [1, 2, 3]
b = a[:]        // b is a SHALLOW COPY of a
b.push 4
print a         // [1, 2, 3]  -- a is unchanged
print b         // [1, 2, 3, 4]

Note that [:] makes a shallow copy. If your list contains other lists or maps, those inner objects are still shared:

a = [[1, 2], [3, 4]]
b = a[:]
b[0].push 99
print a[0]      // [1, 2, 99]  -- inner list is still shared

To avoid that, you would need to copy each element individually:

a = [[1, 2], [3, 4]]
b = []
for item in a
    b.push item[:]
end for
b[0].push 99
print a[0]      // [1, 2]  -- truly independent now

This same behavior applies to maps. Assigning a map to a new variable does not copy it; use the + operator with an empty map (myMap + {}) to make a shallow copy of a map.

Copying a list

User: How do I make a copy of a list in MiniScript so I can modify it without affecting the original?

Assistant: In MiniScript, assigning a list to a new variable does not copy it — both variables refer to the same list. To get an independent copy, use the slice operator [:].

original = [1, 2, 3, 4, 5]

// This does NOT make a copy -- both point to the same list:
notACopy = original
notACopy.push 6
print original  // [1, 2, 3, 4, 5, 6] -- original was changed!

// This DOES make a copy:
original = [1, 2, 3, 4, 5]
copy = original[:]
copy.push 99
print original  // [1, 2, 3, 4, 5] -- original is unaffected
print copy      // [1, 2, 3, 4, 5, 99]

The slice operator is typically used to get a smaller sublist, but if you omit both the start and the end index, it copies from the beginning to the end. In other words, this [:] syntax creates a shallow copy of the list. This means the list itself is new, but if it contains other lists or maps, those inner elements are still shared references. If you need a deep copy (where nested structures are also independent), you need to copy each level manually:

deepCopy = function(lst)
    result = []
    for item in lst
        if item isa list then
            result.push deepCopy(item)
        else
            result.push item
        end if
    end for
    return result
end function

nested = [[1, 2], [3, 4]]
independent = deepCopy(nested)
independent[0].push 99
print nested       // [[1, 2], [3, 4]] -- unaffected
print independent  // [[1, 2, 99], [3, 4]]

A few things to note:

• [:] is the idiomatic way to shallow-copy a list in MiniScript
• For simple lists of numbers or strings, a shallow copy is all you need since those types are values, not references

Creating and using maps

User: How do I create and use a map (dictionary) in MiniScript?

Assistant: Maps (sometimes called dictionaries) are one of MiniScript's core data types. You create them with curly braces and access values by key using bracket or dot notation.

Creating a map:

// Empty map
m = {}

// Map with initial key-value pairs
person = {"name": "Alice", "age": 30, "city": "Portland"}

Accessing and setting values:

You can read or write a value for a key by putting the key after the map reference in square brackets, like person["name"]. When the key happens to be a valid MiniScript identifier (i.e. starts with a letter or underscore, and contains only letters, underscores, and numbers), then you can also use dot notation, as shown here:

print person["name"]    // Alice
print person.name       // Alice (dot notation shorthand)

person["email"] = "alice@example.com"  // add a new entry
person.age = 31                        // update an existing entry

Checking for keys and removing entries:

if person.hasIndex("email") then print "Has email"
person.remove "email"

Iterating over a map:

for kv in person
    print kv.key + ": " + kv.value
end for
// name: Alice
// age: 31
// city: Portland

You can also get keys and values separately:

print person.indexes   // ["name", "age", "city"]
print person.values    // ["Alice", 31, "Portland"]

Other useful properties:

print person.len       // 3 (number of key-value pairs)

Note that bracket notation (m["key"]) works with any string, while dot notation (m.key) only works when the key is a valid identifier. Use bracket notation when keys contain spaces or special characters, or when the key is stored in a variable:

key = "name"
print person[key]      // Alice

Map dot syntax vs bracket syntax

User: What's the difference between myMap.key and myMap["key"] in MiniScript?

Assistant: In MiniScript, myMap.key and myMap["key"] are functionally identical — they both look up the value associated with the string key "key" in the map. Dot notation is simply a convenient shorthand for bracket notation.

m = {"name": "Alice", "age": 30}

print m.name       // Alice
print m["name"]    // Alice  (same thing)

m.score = 100
print m["score"]   // 100  (dot assignment works too)

The only difference is practical: dot notation only works with keys that are valid identifiers (letters, digits, and underscores, not starting with a digit). If your key contains spaces, punctuation, or starts with a number, you must use bracket notation:

m = {}
m["full name"] = "Bob Smith"   // works fine
// m.full name = "Bob Smith"   // would NOT work (space in key)

m["42"] = "answer"
// m.42 = "answer"            // would NOT work (starts with digit)

The other important difference is that bracket notation lets you use a variable or expression as the key, while dot notation always uses a literal name:

m = {"x": 10, "y": 20}

key = "x"
print m[key]    // 10  (looks up the value of key, which is "x")
print m.key     // null (looks for a literal key called "key")

In short: use dot notation for clean, readable code when your keys are simple identifiers and known at write time. Use bracket notation when keys are dynamic (stored in variables) or contain characters that are not valid in an identifier.

Reference types vs value types (maps)

User: I assigned a map to a new variable and changed the new variable, but the original map changed too. What's going on?

Assistant: In MiniScript, maps (and lists) are reference types. When you assign a map to a new variable, you are not making a copy — both variables point to the same map in memory. Any change through one variable is visible through the other.

original = {"name": "Alice", "score": 10}
copy = original
copy.score = 99
print original.score  // 99 -- original changed too!

Both original and copy refer to the exact same map, so changing copy.score also changes original.score.

To make an independent copy, use the + operator with an empty map:

original = {"name": "Alice", "score": 10}
copy = original + {}
copy.score = 99
print original.score  // 10 -- original is unaffected

The expression original + {} creates a new map and merges all key-value pairs from original into it. After that, copy and original are separate maps, and changes to one do not affect the other.

The same principle applies to lists. Assigning a list to a new variable gives you two references to the same list. To copy a list, use the slice shorthand original[:].

Defining and calling functions

User: How do I define and call a function in MiniScript?

Assistant: In MiniScript, you define a function with the function keyword and close it with end function. You assign it to a variable, then call it by name.

Basic function with no parameters:

sayHello = function
    print "Hello!"
end function

sayHello

Function with parameters:

greet = function(name)
    print "Hello, " + name + "!"
end function

greet "Alice"

Function with a default parameter value:

greet = function(name="World")
    print "Hello, " + name + "!"
end function

greet           // prints: Hello, World!
greet "Bob"     // prints: Hello, Bob!

Function that returns a value:

square = function(x)
    return x * x
end function

print square(4)   // prints: 16

Note the parentheses rules: when calling a function as a standalone statement (not part of a larger expression), parentheses are optional and discouraged — so you write greet "Alice" rather than greet("Alice"). But when the function call is embedded in an larger statement, such as passing its result to print, you do need parentheses: print square(4).

You can also store a reference to a function using @ and call it later:

f = @square
print f(5)   // prints: 25

Function parameters and default values

User: Can MiniScript functions have default parameter values?

Assistant: Yes! You specify default values right in the parameter list using =:

greet = function(name="World", greeting="Hello")
    print greeting + ", " + name + "!"
end function

greet                    // Hello, World!
greet "Alice"            // Hello, Alice!
greet "Bob", "Hi"        // Hi, Bob!

If a caller omits an argument, the parameter takes its default value. Parameters without defaults get null if not provided:

test = function(a, b=10)
    print "a=" + a + ", b=" + b
end function

test 5        // a=5, b=10
test 5, 20    // a=5, b=20
test          // a=, b=10

The return statement

User: How do I return a value from a function in MiniScript?

Assistant: Use the return keyword to send a value back from a function:

square = function(x)
    return x * x
end function

print square(4)   // 16

You can return early from anywhere in the function:

safeDiv = function(a, b)
    if b == 0 then return null
    return a / b
end function

print safeDiv(10, 3)   // 3.333333
print safeDiv(10, 0)   // null

A function that doesn't explicitly return a value returns null by default:

sayHi = function
    print "Hi!"
end function

result = sayHi    // prints "Hi!"
print result      // null

You can return any type — numbers, strings, lists, maps, even other functions:

makePair = function(a, b)
    return [a, b]
end function

print makePair("x", 42)   // ["x", 42]

Note that return doesn't need parentheses — return x * x is preferred over return(x * x).

Variable scope

User: How does variable scope work in MiniScript?

Assistant: MiniScript has a straightforward scoping model built around three layers: local, outer, and global.

Variables are local by default. Any assignment to an unqualified name creates or updates a variable in the current local scope.

Unqualified reads walk up the scope chain. When you read a variable, MiniScript looks first in locals, then the enclosing (outer) scope, then globals:

x = 100
f = function
    print x   // finds x in outer scope; prints 100
end function
f

Unqualified writes always target local scope. Even if a variable exists in an outer scope, assigning to it without a qualifier creates a new local variable instead:

x = 100
f = function
    x = 42       // creates a NEW local x; does NOT change the outer x
end function
f
print x          // still 100

Use outer or globals to write to other scopes:

x = 100
f = function
    outer.x = 42     // modifies x in the enclosing scope
end function
f
print x              // now prints 42

To summarize: reads automatically search upward through scopes, but writes always stay local unless you explicitly say outer.varName or globals.varName.

local, outer, and global

User: What's the difference between local, outer, and global variables?

Assistant: MiniScript has three scope levels: local, outer, and globals.

Local scope (the default):

When you assign a variable inside a function, it's local to that function by default:

demo = function
    x = 10          // x is local to demo
    print x         // 10
end function
demo
// x is not accessible out here

Global scope (globals):

Globals are variables defined at the top level of your program, outside any function. Inside a function, use globals. to read or write them explicitly:

score = 100    // global (defined at top level)

addPoints = function(n)
    globals.score += n
end function

addPoints 50
print score    // 150

Without globals., the assignment score += n would create a new local variable instead of updating the global one.

Outer scope (outer):

outer refers to the scope of the enclosing function — useful when you have a function defined inside another function:

makeCounter = function
    count = 0
    f = function
        outer.count += 1
        return outer.count
    end function
    return @f
end function

counter = makeCounter
print counter   // 1
print counter   // 2
print counter   // 3

Here, the inner function f uses outer.count to access and modify count in makeCounter's scope.

Summary of the rules:

• Reading an unqualified variable searches: local → outer → globals
• Writing an unqualified variable always targets the local scope
• Use outer.varName to write to the enclosing function's scope
• Use globals.varName to write to the top-level scope

Prototype-based OOP

User: How do I create classes and objects in MiniScript?

Assistant: MiniScript uses prototype-based OOP, not class-based. There's no class keyword. Instead, you create a map, add properties and methods to it, then use new to create instances.

Defining a "class" (prototype):

Dog = {}
Dog.name = "unknown"
Dog.speak = function
    print self.name + " says Woof!"
end function

Creating an instance:

myDog = new Dog
myDog.name = "Rex"
myDog.speak   // Rex says Woof!

new Dog creates a new map whose __isa property points to Dog. This causes the instance to inherit all of Dog's properties and methods. Setting a property on the instance doesn't affect the prototype.

Inheritance:

Animal = {}
Animal.name = "unknown"
Animal.speak = function
    print self.name + " makes a sound"
end function

Dog = new Animal
Dog.speak = function
    print self.name + " says Woof!"
end function

Cat = new Animal
Cat.speak = function
    print self.name + " says Meow!"
end function

rex = new Dog
rex.name = "Rex"
rex.speak      // Rex says Woof!

whiskers = new Cat
whiskers.name = "Whiskers"
whiskers.speak  // Whiskers says Meow!

Any lookup of a map entry (such as whiskers.speak above) looks first in that map, but if it's not found, then MiniScript walks the __isa chain until it either finds the given key, or throws a "Key Not Found" error. This is how properties and methods are inherited, and can be overridden, in the class hierarchy.

Key points:

• "Classes" are just maps used as prototypes
• new creates an instance with __isa pointing to the prototype
• self is automatically available inside methods — don't declare it as a parameter
• Property lookup walks the __isa chain: instance → prototype → prototype's prototype → etc.
• There are no constructors — just set properties after new, or use a factory method

The new operator and __isa

User: What does the new operator do in MiniScript?

Assistant: The new operator creates a new map and sets its __isa property to point to the given prototype. This establishes an inheritance relationship.

Animal = {}
Animal.name = "unknown"
Animal.speak = function
    print self.name + " makes a sound"
end function

dog = new Animal
print dog        // {"__isa": {...}}
print dog.name   // unknown (inherited from Animal)

How __isa works:

When you access a property on a map and it's not found, MiniScript follows the __isa chain to look it up in the prototype. It's like a "parent" pointer:

dog.name = "Rex"    // sets name on the instance
print dog.name      // Rex (found on instance, no need to check __isa)
dog.speak           // Rex makes a sound (speak found via __isa → Animal)

Chain of inheritance:

__isa chains can be multiple levels deep:

Animal = {}
Animal.legs = 4

Dog = new Animal
Dog.sound = "Woof"

myDog = new Dog
print myDog.sound   // Woof (from Dog)
print myDog.legs    // 4 (from Animal, via Dog.__isa)

The lookup chain is: myDog → Dog → Animal.

Checking inheritance:

You can use isa to check if an object inherits from a prototype:

print myDog isa Dog     // 1 (true)
print myDog isa Animal  // 1 (true)
print myDog isa map     // 1 (true — all objects are maps)

You can also inspect __isa directly: print Dog.__isa == Animal prints 1. (But be careful, this only checks the immediate parent, not more distant ancestors.)

Using self in methods

User: How do I access an object's own properties inside its methods in MiniScript?

Assistant: Use the self keyword. When a method is called via dot notation, MiniScript automatically sets self to refer to the object the method was called on. You do not declare self as a parameter — it's provided automatically.

Dog = {}
Dog.name = "unknown"
Dog.tricks = 0

Dog.describe = function
    print self.name + " knows " + self.tricks + " tricks"
end function

Dog.learnTrick = function
    self.tricks += 1
    print self.name + " learned a trick!"
end function

rex = new Dog
rex.name = "Rex"
rex.describe       // Rex knows 0 tricks
rex.learnTrick     // Rex learned a trick!
rex.describe       // Rex knows 1 tricks

Important: you must use self.propertyName to access the object's properties. A bare name inside a method would look for a local or global variable called name, not the object's property:

Dog.broken = function
    print name       // WRONG: looks for local/global variable "name"
    print self.name  // RIGHT: accesses this object's name property
end function

self also works for calling other methods on the same object:

Dog.greet = function
    self.describe           // call another method on the same object
    print "Nice to meet you!"
end function

Accessing superclass properties

User: How do I access a property or method defined in some superclass?

Assistant: In most cases, you don't need to do anything special. MiniScript's prototype chain (__isa) automatically walks up the inheritance hierarchy when you access a property or call a method.

Automatic lookup via __isa:

When you access a property on a map and it isn't found directly on that map, MiniScript follows the __isa chain to look it up in the parent prototype, then the grandparent, and so on.

Shape = {}
Shape.color = "red"
Shape.describe = function
    print "A " + self.color + " shape"
end function

Circle = new Shape
Circle.radius = 10

c = new Circle
print c.color       // red (found via Circle.__isa -> Shape)
c.describe          // A red shape (method found the same way)
print c.radius      // 10 (found via c.__isa -> Circle)

Here, c doesn't have color or describe directly, but MiniScript walks the chain: c -> Circle -> Shape, and finds them there.

Overriding and still accessing the parent:

If a subclass overrides a method but you want to also invoke the parent version, use super:

Shape = {}
Shape.describe = function
    print "A shape with " + self.sides + " sides"
end function

Triangle = new Shape
Triangle.sides = 3
Triangle.describe = function
    super.describe
    print "  (it's a triangle!)"
end function

t = new Triangle
t.describe
// A shape with 3 sides
//   (it's a triangle!)

Key points:

• Property reads automatically check __isa parents. You just use self.propName and it works.
• super is only needed when you've overridden a method in the current prototype and want to call the parent's version of that same method.
• The lookup chain can be as many levels deep as you like.

super

User: What does super do?

Assistant: super is a keyword you use inside a method to invoke the parent prototype's version of that same method. It works just like self, except the property lookup starts one level up the __isa chain — it skips the current object's prototype and begins searching from the grandparent.

This is most useful when you override a method but still want to include the behavior defined in the parent.

Basic example — overriding and calling the parent method:

Animal = {}
Animal.describe = function
    print self.name + " is an animal"
end function

Dog = new Animal
Dog.describe = function
    super.describe    // calls Animal.describe
    print "  ...specifically, a dog!"
end function

rex = new Dog
rex.name = "Rex"
rex.describe
// Output:
// Rex is an animal
//   ...specifically, a dog!

Notice that even though super.describe calls the Animal version, self inside that parent method still refers to rex (the actual instance). So self.name correctly prints "Rex".

Multi-level example:

Shape = {}
Shape.describe = function
    print "I am a shape"
end function

Polygon = new Shape
Polygon.describe = function
    super.describe
    print "  with " + self.sides + " sides"
end function

RegularPolygon = new Polygon
RegularPolygon.describe = function
    super.describe
    print "  and all sides equal"
end function

hex = new RegularPolygon
hex.sides = 6
hex.describe
// Output:
// I am a shape
//   with 6 sides
//   and all sides equal

Each level calls super.describe, which chains up through RegularPolygon -> Polygon -> Shape, so all three messages print in order.

Key points to remember:

• super is only meaningful inside a method invoked via dot syntax.
• super.foo starts the lookup from the parent of the prototype where the current method is defined, not from self.__isa. This means it always goes exactly one level up from the method's own prototype, even if the instance is further down the chain.
• You can use super to access properties too, not just methods. For example, super.sound would retrieve the sound property from the parent prototype.

File operations

User: How do I read and write files in MiniScript?

Assistant: In command-line MiniScript and Mini Micro, you can use the file module to read and write text files.

Reading a file:

content = file.readLines("/path/to/myfile.txt")
// Returns a list of strings, one per line

for line in content
    print line
end for

Or read the entire file as a single string:

text = file.open("/path/to/myfile.txt").read

Writing a file:

// Write a list of lines
lines = ["line 1", "line 2", "line 3"]
file.writeLines "/path/to/output.txt", lines

Or write a single string:

file.open("/path/to/output.txt", "w").write "Hello, file!"

Appending to a file:

f = file.open("/path/to/log.txt", "a")
f.write "New log entry" + char(10)
f.close

In Mini Micro, file paths are relative to the virtual filesystem. Common paths include:

• /usr/ — user files
• /sys/ — system files (read-only)

file.writeLines "/usr/mydata.txt", ["apple", "banana", "cherry"]
data = file.readLines("/usr/mydata.txt")
print data   // ["apple", "banana", "cherry"]

Note: File I/O availability depends on the MiniScript host environment. The command-line tool and Mini Micro both support it, but a web-based MiniScript environment may not.

Listing files and directories

User: How do I list the files in a directory in MiniScript?

Assistant: Use file.children to get a list of files and directories within a given path:

items = file.children("/usr/")
for item in items
    print item
end for

Each entry is a string with the full path. You can check whether an entry is a file or directory using file.info:

items = file.children("/usr/")
for item in items
    info = file.info(item)
    if info.isDirectory then
        print "[DIR]  " + item
    else
        print "[FILE] " + item + " (" + info.size + " bytes)"
    end if
end for

The file.info function returns a map with properties like size, date, and isDirectory.

In Mini Micro, common directories include /usr/ (user files) and /sys/ (system files). In command-line MiniScript, you can use standard filesystem paths for your operating system.

Recursion

User: Can I write a recursive function MiniScript?

Assistant: Yes! MiniScript fully supports recursive functions. A recursive function is one that calls itself, and it works just like in other languages. The key requirement is that you need a base case to stop the recursion, or you'll get a stack overflow error.

Here's a simple example that computes a factorial:

factorial = function(n)
    if n <= 1 then return 1
    return n * factorial(n - 1)
end function

print factorial(5)   // prints 120

factorial(5) calls factorial(4), which calls factorial(3), and so on, until n reaches 1. That's the base case, which returns 1 and stops the recursion. The results then multiply back up the chain: 1 * 2 * 3 * 4 * 5 = 120.

A couple of things to keep in mind:

• Always include a base case that returns without calling itself again
• Recursion isn't ideal for problems that recurse thousands of levels deep, or recurse multiple times per call; for those cases, consider rewriting with a while loop instead

What is Mini Micro?

User: What is Mini Micro?

Assistant: Mini Micro is a virtual computer (sometimes called a "fantasy console" or "fantasy computer") that uses MiniScript as its built-in programming language. It provides a complete, self-contained environment for writing and running MiniScript programs.

Key features of Mini Micro include:

• A built-in code editor, so you can write and run code without any external tools
• A 960x640 pixel display with 8 layers that can each independently be one of five types: text display, pixel (bitmap) display, sprite layer, tile map, or solid color — this layered system makes it easy to build games and visual applications
• Keyboard, mouse, and gamepad input support
• Sound capabilities for playing and synthesizing sounds
• A virtual filesystem for saving and loading files, including code and data

Mini Micro is designed to be an approachable environment for learning programming and making games. Because MiniScript emphasizes readability and simplicity, and Mini Micro provides everything you need in one package, beginners can start creating interactive programs right away without dealing with complex development tool setup.

You can download Mini Micro for free from https://miniscript.org/MiniMicro/. It runs on Mac, Windows, and Linux. There is also a web-based version you can try directly in your browser.

Mini Micro basics

User: What are the basic commands for working in Mini Micro?

Assistant: Mini Micro has a built-in command-line environment where you can type commands directly. Here are the essentials:

edit — Opens the built-in code editor where you write your program. Press Control-W or click the Close button to return to the command line. Optionally, you may give edit a file name to load and then edit.

run — Runs the program currently in the editor. Like edit, you make give run a file name to load and run.

save "filename" — Saves the current program to a file:

save "/usr/myProgram.ms"

You may omit the filename when saving a previously loaded or saved program. When you supply a file name, it may be a full path as shown here, or just the name of a program in the current directory. The ".ms" extension is optional in both cases.

load "filename" — Loads a program from a file into memory, making it the current program:

load "/usr/myProgram.ms"

Again you may supply a full or partial path, with or without ".ms".

dir — Lists files in the current directory.

cd "path" — Changes the current directory. cd by itself takes you back to "/usr".

You can also type and run MiniScript code directly at the command prompt without using the editor:

> print "Hello!"
Hello!
> x = 2 + 3
> x
5

Common workflow:

1. Type edit to open the editor
2. Write your program
3. Press Control-W to exit the editor
4. Type run to execute it
5. Type save "myProgram" to save
6. Later, load "myProgram" to load it back

The /usr/ directory is the main place to save your files. The /sys/ directory contains system files and libraries, and is read-only.

Keyboard input in Mini Micro

User: How do I check for keyboard input in a Mini Micro program?

Assistant: Mini Micro provides the key module for keyboard input.

Check if any key is available:

while true
    if key.available then
        k = key.get
        print "You pressed: " + k
    end if
    yield
end while

key.available returns true if a keypress is waiting; key.get retrieves it as a string.

Check if a specific key is currently held down:

while true
    if key.pressed("space") then print "Space is held!"
    if key.pressed("left") then print "Left arrow!"
    if key.pressed("right") then print "Right arrow!"
    yield
end while

key.pressed checks the real-time state of a key, which is better for game controls.

Common key names for key.pressed: "left", "right", "up", "down", "space", "return", "escape", "tab", or any letter like "a", "w", etc.

Simple input example — move a character:

x = 480
y = 320
while true
    if key.pressed("left") then x -= 3
    if key.pressed("right") then x += 3
    if key.pressed("up") then y += 3
    if key.pressed("down") then y -= 3

    gfx.clear
    gfx.fillEllipse x-10, y-10, 20, 20, color.green
    yield
end while

Note the yield call in the loop — this is essential in Mini Micro to give the system time to process events and update the display.

Colors in Mini Micro

User: How do I work with colors in Mini Micro?

Assistant: Mini Micro represents colors as strings in "#RRGGBB" or "#RRGGBBAA" hex format. The color module provides many predefined colors.

Predefined colors:

print color.red      // #FF0000
print color.green    // #00FF00
print color.blue     // #0000FF
print color.white    // #FFFFFF
print color.black    // #000000
print color.yellow   // #FFFF00
print color.orange   // #FF8800

Creating custom colors:

Use the color.rgb or color.rgba functions:

myColor = color.rgb(128, 0, 255)       // purple
print myColor                           // #8000FF

semiTransparent = color.rgba(255, 0, 0, 128)  // semi-transparent red
print semiTransparent                           // #FF000080

Arguments are 0–255 for each channel (red, green, blue, and optionally alpha).

Using colors for drawing:

gfx.fillRect 100, 100, 200, 150, color.blue
gfx.drawRect 100, 100, 200, 150, color.white

gfx.fillEllipse 400, 300, 80, 80, color.rgb(255, 128, 0)

Using colors with text:

text.color = color.yellow
text.backColor = color.navy
print "Yellow on navy!"

You can also compare colors directly since they're just strings:

c = color.red
if c == "#FF0000" then print "It's red!"

Text display formatting

User: How do I control text positioning and color on Mini Micro's text display?

Assistant: Mini Micro has a text display layer that works like a terminal grid with rows and columns.

Setting cursor position:

text.row = 15
text.column = 20
print "Hello!"   // prints at row 15, column 20

Rows are numbered from 0 (bottom) to 25 (top). Columns are numbered from 0 (left) to 67 (right).

Setting text color and background:

text.color = color.yellow
text.backColor = color.blue
print "Yellow text on blue background"

Placing text at specific locations:

text.row = 20
text.column = 30
text.color = color.lime
print "Score: 100"

Clearing the text display:

text.clear

Writing a single character at a position:

text.setCell 10, 5, "X"   // column 10, row 5, character "X"

Getting info about a cell:

ch = text.cell(10, 5)     // get character at column 10, row 5

Practical example — a simple status bar:

text.clear
text.row = 25
text.column = 0
text.color = color.white
text.backColor = color.gray
print " " * 68   // fill top row with gray
text.row = 25
text.column = 2
print "My Game v1.0"
text.backColor = color.black

Pixel graphics with gfx

User: How do I draw shapes and lines on the screen in Mini Micro?

Assistant: Mini Micro has a gfx (pixel graphics) display layer for drawing shapes, lines, and pixels.

Drawing rectangles:

gfx.fillRect 100, 100, 200, 150, color.blue       // filled rectangle
gfx.drawRect 100, 100, 200, 150, color.white       // outline only
// Arguments: x, y, width, height, color

Drawing ellipses (and circles):

gfx.fillEllipse 400, 300, 100, 100, color.red      // filled circle
gfx.drawEllipse 400, 300, 100, 100, color.yellow    // circle outline
// For a circle, use the same width and height

Drawing lines:

gfx.line 0, 0, 960, 640, color.green
// Arguments: x1, y1, x2, y2, color

Drawing individual pixels:

gfx.setPixel 480, 320, color.white

Clearing the screen:

gfx.clear color.black   // clear to black
gfx.clear               // clear to transparent

Example — drawing a simple scene:

gfx.clear color.aqua
// Ground
gfx.fillRect 0, 0, 960, 200, color.green
// Sun
gfx.fillEllipse 750, 500, 80, 80, color.yellow
// House
gfx.fillRect 300, 200, 200, 150, color.brown
gfx.fillPoly [[300, 350], [400, 450], [500, 350]], color.red
// Door
gfx.fillRect 370, 200, 60, 100, color.maroon

The screen is 960x640 pixels by default, with (0,0) at the bottom-left corner.

Loading and drawing images

User: How do I load and draw an image in Mini Micro?

Assistant: Use file.loadImage to load an image file, then draw it on the gfx display layer.

Loading and drawing an image:

img = file.loadImage("/sys/pics/Wumpus.png")
gfx.drawImage img, 300, 100  // draw with lower-left corner at x=300, y=100

Drawing at a specific size:

gfx.drawImage img, 100, 100, 200, 150
// Arguments: image, left, bottom, width, height (scales the image)

Getting image info:

print img.width    // width in pixels
print img.height   // height in pixels

Drawing part of an image (source rect):

gfx.drawImage img, 100, 100, 64, 64, 0, 0, 32, 32
// Draws a 32x32 portion (from bottom-left of image) scaled to 64x64 on screen

Using images with sprites (more common for games):

img = file.loadImage("/sys/pics/animals/cat.png")
sp = new Sprite
sp.image = img
sp.x = 480
sp.y = 320
display(4).sprites.push sp

Mini Micro supports PNG files with or without transparency, as well as JPEG files.

## Display layers in Mini Micro

**User:** How do Mini Micro's display layers work?

**Assistant:** Mini Micro has 8 display layers, numbered 0 through 7, stacked from front (0) to back (7). Each layer can be independently configured as one of several display types.

**The default layer setup:**

- `display(0)` — off
- `display(1)` — off
- `display(2)` — off
- `display(3)` — TextDisplay (`text` - where `print` and `input` go)
- `display(4)` — SpriteDisplay (where sprites live)
- `display(5)` — PixelDisplay (`gfx` — the default drawing target)
- `display(6)` — off
- `display(7)` — SolidColor (background)

**Accessing a specific layer:**

layer = display(5) layer.clear color.black

**Changing a layer's mode:**

You can change the display mode of any layer by assigning to its `.mode` property:

display(4).mode = displayMode.pixel

Note that this actually changes the object that `display(n)` returns.  So, if you're going to get and keep a reference to a display for future use, you should always do this _after_ setting the mode:

display(4).mode = displayMode.pixel gfx2 = display(4)

**Pointing `gfx` or `text` to a specific layer:**

`gfx` and `text` are global variables automatically set on boot (or by the `clear` command) to point to display 5 and 3, respectively.  But you can reassign them as you wish:

display(6).mode = displayMode.text text = display(6) // now text commands output on layer 6 display(3).mode = displayMode.pixel gfx = display(3) // now gfx commands draw on layer 3

## Mouse input in Mini Micro

**User:** How do I get mouse input in Mini Micro?

**Assistant:** Mini Micro provides the `mouse` module for tracking the mouse position and button state.

**Getting mouse position:**

while true text.clear print "Mouse X: " + mouse.x print "Mouse Y: " + mouse.y yield end while

`mouse.x` and `mouse.y` give the current position in screen coordinates (0–959 x, 0–639 y, with origin at bottom-left).

**Checking mouse button state:**

while true if mouse.button then gfx.fillEllipse mouse.x-5, mouse.y-5, 10, 10, color.red end if yield end while

`mouse.button` returns `1` (true) when the left mouse button is held down, and `0` (false) otherwise.  To check other buttons, supply a button number; for example, `mouse.button(1)` reports whether the right mouse button is currently pressed.

**Detecting clicks (press and release):**

wasDown = false while true if mouse.button and not wasDown then // Mouse was just clicked print "Click at " + mouse.x + ", " + mouse.y end if wasDown = mouse.button yield end while

**Practical example — a simple drawing program:**

gfx.clear color.white while true if mouse.button then gfx.fillEllipse mouse.x-3, mouse.y-3, 6, 6, color.black end if yield end while

Remember to include `yield` in your loop to give the system time to update.  Press Control-C to break out of the infinite loop.

## The `import` command

**User:** How do I use the `import` command in Mini Micro?

**Assistant:** The `import` command loads and runs another MiniScript file, making its global variables and functions available in your program.

**Basic usage:**

import "mathUtil"

This looks for a file named `stringUtil.ms` in the standard library paths. After importing, any globals defined in that file are available in a map named `mathUtil`

print mathUtil.dice(6, 2) // returns the sum of two six-sided die rolls

**Where Mini Micro looks for imports:**

The search path for imports is determined by `env.importPaths`, which by default is:

1. The current directory
2. `/usr/lib/`
3. `/sys/lib/`

Mini Micro comes with several useful libraries in `/sys/lib/`, including:
- `stringUtil` — extra string functions
- `listUtil` — extra list functions like `list.init2d`
- `mathUtil` — extra math functions
- `mapUtil` — extra map functions
- `qa` — quality assurance functions (`assert`, etc.)
- `json` — JSON parsing and generation

**Importing your own files:**

If you have a file at `/usr/lib/myHelpers.ms`, you can import it:

import "myHelpers"

**Important notes:**
- You don't include the `.ms` extension in the import string
- `import` runs the file, so any top-level code in the imported file will execute
- If the same file is imported more than once, it runs every time
- `import` is a feature of the Mini Micro environment (and some others), not a feature of the MiniScript language itself

## Playing sounds in Mini Micro

**User:** How do I play sounds in Mini Micro?

**Assistant:** Mini Micro can play sound files using the `Sound` class.

**Loading and playing a sound:**

snd = file.loadSound("/sys/sounds/hit.wav") snd.play

**Controlling volume and speed:**

snd = file.loadSound("/sys/sounds/twinkle.wav") snd.play 0.5 // play at half volume (0 to 1 range) snd.play 1, 2 // full volume, double speed (higher pitch)

**Checking if a sound is playing:**

snd.play while snd.isPlaying yield end while print "Sound finished!"

**Stopping a sound:**

snd.stop

**Playing background music:**

music = file.loadSound("/usr/myMusic.ogg") music.loop // plays the sound on repeat // Later: music.stop // stop the music

Mini Micro includes some built-in sounds in `/sys/sounds/`. You can also load your own `.wav` or `.ogg` files from `/usr/`.

**Quick beep (without loading a file):**

Mini Micro has a built-in "terminal bell" that plays whenever you print `char(7)`, for example:

print "ERROR!" + char(7)

**Synthesized sounds**

Mini Micro has a sophisticated system for synthesizing sounds on the fly.  You can import "/sys/lib/sounds" for a built-in selection of synthesized sounds, and examine that code to see how they are made.  The demo at "/sys/demo/soundLab" is another good way to develop synthesized sounds.

## Sound synthesis

**User:** How do I create sounds from scratch (synthesis) in Mini Micro?

**Assistant:** Mini Micro can generate sounds programmatically using `Sound.init`, which takes four parameters:

1. Duration: how long the sound should be, in seconds
2. Frequency: how many times the waveform should repeat per second
3. Envelope: how the volume of the sound should change over its duration
4. Waveform: what one cycle of the sound looks like

Frequency and envelope can be a single value, or a list of values; in the latter case, the frequency or amplitude is interpolated over the given values.  Waveform is typically one of the built-in `Sound.sineWave`, `Sound.squareWave`, etc., but can also be individual samples as a list.  Moreover, sounds can be mixed (with the `.mix` method, allowing you to build up complex layered sounds.

Here's an example:

bounce = new Sound bounce.init 0.3, [100,1000], [1,0], Sound.sawtoothWave bounce.play

This makes a sound 0.3 seconds long, with a frequency that starts at 100 Hz and rises to 1000 Hz by the end of the sound.  The amplitude starts at 1 (full volume) and fades to 0 by the end, and it uses a sawtooth wave, which gives a retro, 8-bit feel to the sound.

A good way to learn to make your own synthesized sounds is to load "/sys/lib/sounds", run it to hear what the provided sounds sound like, and then `edit` to see the code that creates them.  Another good tool is "/sys/demo/soundLab", which provides a graphical interface for building your own synthesized sounds, and then provides the corresponding MiniScript code.

## Subclasses and `super`

**User:** How do I create a subclass that extends a parent class in MiniScript, and how do I call the parent's method?

**Assistant:** In MiniScript's prototype-based OOP, you create a "subclass" by using `new` on the parent prototype, then overriding or adding methods.

**Creating a subclass:**

Animal = {} Animal.name = "unknown" Animal.speak = function print self.name + " makes a sound" end function

Dog = new Animal Dog.speak = function print self.name + " says Woof!" end function

Cat = new Animal Cat.speak = function print self.name + " says Meow!" end function

**Calling the parent's method with `super`:**

Use `super` inside a method to call the parent (prototype) version of that method:

Animal = {} Animal.describe = function print self.name + " is an animal" end function

Dog = new Animal Dog.describe = function super.describe // calls Animal.describe print " ...specifically, a dog!" end function

rex = new Dog rex.name = "Rex" rex.describe // Rex is an animal // ...specifically, a dog!

`super` works like `self`, but starts the method lookup one level up the `__isa` chain, skipping the current prototype.

**Multi-level inheritance:**

Animal = {} Animal.legs = 4

Pet = new Animal Pet.owner = "unknown"

Dog = new Pet Dog.sound = "Woof"

myDog = new Dog myDog.name = "Rex" myDog.owner = "Alice" print myDog.legs // 4 (inherited from Animal) print myDog.owner // Alice (set on instance, overrides Pet default)

The `__isa` chain is: `myDog` → `Dog` → `Pet` → `Animal`.

## The `yield` function

**User:** What does `yield` do in MiniScript, and when should I use it?

**Assistant:** `yield` pauses execution momentarily to let the host environment process events and update the display.  In Mini Micro, it also waits until the start of the next display frame (which happens 60 times per second).  It's essential in Mini Micro for game loops and animations.

**Why you need it:**

Without `yield`, a tight loop will run as fast as your machine can make it go, which will vary from machine to machine, making the result unpredictable.  Also, the display updates at no more than 60 frames per second, so your processing would be out of sync with the display.  With `yield` in your main loop, your game runs at the same rate as the display updates, and at the same speed on all machines.

**Basic game loop pattern:**

while true yield // update game state end while

**Example — animation:**

x = 0 while x < 960 yield gfx.clear gfx.fillEllipse x, 320, 30, 30, color.red x += 3 end while

**`yield` is also like `wait`:**

The `wait` function pauses for a specific amount of time (in seconds). `yield` is essentially `wait(0.01)` — a very brief pause (about 1/60th of a second by default, synced to the frame rate).

wait 2.0 // pause for 2 seconds yield // pause for the rest of the frame (~1/60s)

**In command-line MiniScript:**

`yield` has minimal effect in command-line MiniScript (no display to update), but it's still good practice in long-running loops to keep the system responsive.

**Key rule:** If your program has a loop that runs continuously (game loop, animation, input polling), always include `yield` in the loop body.

## Sprites in Mini Micro

**User:** How do I create and use sprites in Mini Micro?

**Assistant:** Sprites are images that can be moved around the screen independently. They live on a SpriteDisplay layer.

**Creating a sprite:**

sp = new Sprite sp.image = file.loadImage("/sys/pics/animals/cat.png") sp.x = 480 sp.y = 320 display(4).sprites.push sp

This loads an image, positions the sprite at the center of the screen, and adds it to the default sprite display layer (layer 4).

**Moving a sprite:**

sp.x = 200 sp.y = 400

Just change `.x` and `.y` and the sprite moves automatically on the next frame.

**Scaling and rotating:**

sp.scale = 2 // double size sp.scale = 0.5 // half size sp.rotation = 45 // rotate 45 degrees

**Tinting:**

sp.tint = color.red // tint the sprite red

**Simple example — move a sprite around the screen:**

clear sp = new Sprite sp.image = file.loadImage("/sys/pics/animals/dog.png") sp.x = 480 sp.y = 320 display(4).sprites.push sp

while true sp.x += key.axis("Horizontal") * 3 sp.y += key.axis("Vertical") * 3 yield end while

(Note that `key.axis` allows you to use WASD, arrow keys, or a gamepad.)

**Removing a sprite:**

idx = display(4).sprites.indexOf(sp) if idx != null then display(4).sprites.remove idx

Sprites are drawn in order — later sprites in the list appear in front of earlier ones.

## Sprite animation

**User:** How do I animate a sprite in Mini Micro?

**Assistant:** There are two main ways to animate sprites in Mini Micro: frame-based animation (swapping images) and movement animation.

**Frame-based animation (sprite sheet):**

Load multiple frames and cycle through them:

frames = [] frames.push file.loadImage("/sys/pics/KP/KP-run1.png") frames.push file.loadImage("/sys/pics/KP/KP-run2.png")

sp = new Sprite sp.image = frames[0] sp.x = 480 sp.y = 320 display(4).sprites.push sp

frame = 0 timer = 0 while true timer += 1 if timer % 8 == 0 then // change frame every 8 ticks frame = (frame + 1) % frames.len sp.image = frames[frame] end if yield end while

**Movement animation:**

clear sp = new Sprite sp.image = file.loadImage("/sys/pics/animals/cat.png") sp.x = 100 sp.y = 320 display(4).sprites.push sp

// Smooth movement while sp.x < 800 sp.x += 2 sp.y = 320 + sin(sp.x * 0.05) * 50 // bouncy path yield end while

**Rotation animation:**

sp = new Sprite sp.image = file.loadImage("/sys/pics/shapes/Star.png") sp.x = 480 sp.y = 320 display(4).sprites.push sp

while true yield sp.rotation += 2 // rotate 2 degrees per frame end while

**Combining movement and frames:**

while true if key.pressed("right") then sp.x += 3 timer += 1 if timer % 8 == 0 then frame = (frame + 1) % frames.len sp.image = frames[frame] end if end if yield end while

The key idea is to update sprite properties (`.image`, `.x`, `.y`, `.rotation`, `.scale`) each frame inside a `while` loop with `yield`.

## Collision detection with `Bounds`

**User:** How do I detect collisions between sprites in Mini Micro?

**Assistant:** Mini Micro provides a `Bounds` class for axis-aligned bounding box (AABB) collision detection between sprites.  To use this, set up `localBounds` on each sprite with a `Bounds` reflecting the sprite's collision box.

**Basic collision check using `overlaps`:**

clear sp1 = new Sprite sp1.image = file.loadImage("/sys/pics/animals/cat.png") sp1.x = 200; sp1.y = 300 sp1.localBounds = new Bounds sp1.localBounds.width = sp1.image.width sp1.localBounds.height = sp1.image.height display(4).sprites.push sp1

sp2 = new Sprite sp2.image = file.loadImage("/sys/pics/animals/dog.png") sp2.x = 400; sp2.y = 300 sp2.localBounds = new Bounds sp2.localBounds.width = sp2.image.width sp2.localBounds.height = sp2.image.height display(4).sprites.push sp2

while true sp1.x += key.axis("Horizontal") * 5 sp1.y += key.axis("Vertical") * 5

if sp1.overlaps(sp2) then
    text.row = 25
    text.column = 0
    print "Collision!"
else
    text.clear
end if
yield

end while

The `overlaps` method on a sprite checks if its bounding box intersects another sprite's bounding box.

**Point containment:**

Check if a point (like the mouse) is inside a sprite's bounds:

if sp1.contains(mouse.x, mouse.y) then print "Mouse is over the sprite!" end if

This requires you to have set up `localBounds`, as above.

**Tips:**
- You must always set `.localBounds` for `.overlaps` and `.contains` to work
- You can also do your own collision checking, for example, by computing the distance between two round sprites
- For pixel-perfect collision, you would need to check individual pixels, which is more complex

## Weighted random selection

**User:** How can I pick a random item from a list where some items are more likely than others?

**Assistant:** You can use weighted random selection by assigning weights to each item and picking based on a random number within the total weight.

weightedPick = function(items, weights) total = weights.sum r = rnd * total cumulative = 0 for i in items.indexes cumulative += weights[i] if r < cumulative then return items[i] end for return items[-1] end function

Usage:

items = ["common", "uncommon", "rare", "legendary"] weights = [60, 25, 12, 3]

for i in range(1, 10) print weightedPick(items, weights) end for

In this example, "common" has a 60% chance, "uncommon" 25%, "rare" 12%, and "legendary" 3%.

**Alternative approach using a map:**

lootTable = {"gold coin": 50, "silver ring": 30, "magic sword": 15, "dragon egg": 5}

weightedPick = function(table) total = 0 for kv in table total += kv.value end for r = rnd * total cumulative = 0 for kv in table cumulative += kv.value if r < cumulative then return kv.key end for end function

print weightedPick(lootTable)

The core idea: generate a random number from 0 to the total weight, then walk through the items adding up weights until you pass the random number.

## The `isa` operator

**User:** How do I check whether an object is an instance of a particular type or class in MiniScript?

**Assistant:** Use the `isa` operator. It checks whether a value is of a given type or inherits from a given prototype.

**Checking built-in types:**

x = 42 print x isa number // 1 (true) print x isa string // 0 (false)

s = "hello" print s isa string // 1 (true)

lst = [1, 2, 3] print lst isa list // 1 (true)

m = {"a": 1} print m isa map // 1 (true)

**Checking custom prototypes:**

Animal = {} Dog = new Animal Cat = new Animal

rex = new Dog

print rex isa Dog // 1 (true) print rex isa Animal // 1 (true — Dog inherits from Animal) print rex isa Cat // 0 (false) print rex isa map // 1 (true — all objects are maps)

`isa` walks the entire `__isa` chain, so it works for multi-level inheritance.

**Checking for null and funcRef:**

x = null print x isa null // equivalent to: print x == null

f = @print print f isa funcRef // 1 (true)

**Practical use — type-safe function:**

process = function(val) if val isa number then print "Number: " + val * 2 else if val isa string then print "String: " + val.upper else if val isa list then print "List with " + val.len + " items" end if end function

## TileDisplay basics

**User:** How do I set up and use a TileDisplay in Mini Micro?

**Assistant:** A TileDisplay shows a grid of small images (tiles) — perfect for maps, levels, and tile-based games.

**Setting up a TileDisplay:**

clear display(4).mode = displayMode.tile td = display(4)

// Load a tile set image td.tileSet = file.loadImage("/sys/pics/TileShapes.png") td.tileSetTileSize = 64 // each tile is 64x64 pixels in the tile set td.cellSize = 64 // each cell on screen is 64x64 pixels

td.extent = [15, 10] // grid is 15 columns by 10 rows td.clear 16 // clear all cells to tile 16```

Setting tiles in cells:

td.setCell 0, 0, 1    // set column 0, row 0 to tile index 1
td.setCell 5, 3, 4    // set column 5, row 3 to tile index 4
td.setCell 3, 0, null // clear the tile in column 3, row 0

Setting a cell to null makes it empty/transparent. Indices count left-to-right, top-to-bottom across the tile set image. The view command provides a quick way to look up tile indexes:

view td.tileSet

Filling a grid:

The setCell method accepts a list of coordinates for both X and Y, which can be combined to fill a rectangular range of cells all at once:

td.setCell range(4, 14), range(0, 9), 22

Getting a tile value:

tileIdx = td.cell(5, 3)
print tileIdx

Scrolling the tile display:

td.scrollX = 100   // scroll 100 pixels right
td.scrollY = 50    // scroll 50 pixels up

This is useful for side-scrolling or top-down games where the map is larger than the screen.

Practical tip: Design your tile set image as a grid of equally-sized tiles. The tileSetTileSize tells Mini Micro how to slice up that image into individual tiles.

Tile sets and cell indexing

User: How do tile sets work in Mini Micro? How do I specify which tile appears in each cell?

Assistant: A tile set is a single image containing all your tiles arranged in a grid. Mini Micro slices it up based on the tile size you specify.

How tile indexing works:

Tiles are numbered starting from 0, reading left-to-right, top-to-bottom across the tile set image:

// If your tile set is 4 tiles wide:
// Index:  0  1  2  3
//         4  5  6  7
//         8  9  10 11

Setting up the tile set:

display(4).mode = displayMode.tile
td = display(4)
td.tileSet = file.loadImage("/sys/pics/SimplePlatformTiles.png")
td.tileSetTileSize = 32   // each tile is 32x32 in the image
td.cellSize = 32           // each cell on screen is 32x32

Placing tiles:

td.setCell 0, 0, 1    // place tile #1 at column 0, row 0
td.setCell 1, 0, 3    // place tile #3 at column 1, row 0
td.setCell 2, 0, null // tile 0 = empty/blank

Building a map from data:

mapData = [[1, 1, 1, 1, 1],
           [1, 0, 0, 0, 1],
           [1, 0, 0, 0, 1],
           [1, 0, 2, 0, 1],
           [1, 1, 1, 1, 1]]

for row in mapData.indexes
    for col in mapData[row].indexes
        td.setCell col, mapData.len - 1 - row, mapData[row][col]
    end for
end for

Note: row 0 in TileDisplay is at the bottom of the screen, so you may need to flip your data if you define it top-to-bottom, as shown above.

Tile tinting:

You can tint individual cells:

td.setCellTint 5, 3, color.red   // tint the cell at (5,3) red

This lets you reuse the same tile with different colors.

Hex grids with TileDisplay

User: Can Mini Micro's TileDisplay support hexagonal grids?

Assistant: Yes! Mini Micro's TileDisplay has built-in support for hexagonal grids. You enable it by setting the oddRowOffset or oddColOffset property.

Setting up a hex grid (offset rows):

display(4).mode = displayMode.tile
td = display(4)
td.tileSet = file.loadImage("/sys/pics/hextiles-55x64.png")
td.tileSetTileSize = [55, 64]
td.cellSize = [55, 64]
td.extent = [10, 8]
td.clear 0
td.oddRowOffset = 0.5    // offset odd rows by half a cell width
td.overlap = [0, 16]   // overlap vertically for tight packing

The key properties:

• oddRowOffset — shifts odd-numbered rows by this fraction of a cell width (0.5 for hex grids)
• overlap — controls spacing between cells; for hex tiles that are taller than wide, an overlap of 1/4 the cell height is typical

Filling the hex grid:

for col in range(td.extent[0] - 1)
    for row in range(td.extent[1] - 1)
        td.setCell col, row, floor(rnd * 6)
    end for
end for

The cell addressing still uses column and row numbers just like a regular grid — the display handles the visual offset automatically.

Tips for hex grids:

• Design your hex tile images to overlap slightly so they tessellate properly
• oddColOffset works similarly but shifts odd columns vertically instead
• The coordinate system is still rectangular — the visual offset is purely a display feature
• For hex grid neighbor calculations, remember that odd and even rows have different neighbor offsets

Using list.init2d from listUtil

User: How do I create a 2D array in MiniScript?

Assistant: MiniScript doesn't have a built-in 2D array type, but you can use a list of lists. The listUtil library provides a convenient list.init2d function for this.

Using list.init2d (recommended):

import "listUtil"

grid = list.init2d(5, 3, 0)   // 5 rows, 3 columns, filled with 0
grid[2][1] = 42
print grid[2][1]   // 42

Why you need list.init2d:

You might be tempted to do this:

// WRONG — all rows share the same inner list!
grid = [[0]*5] * 3
grid[0][0] = 99
print grid[1][0]   // 99 — oops, all rows changed!

The * operator on lists creates references to the same list, not copies. list.init2d avoids this by creating independent lists for each row.

Building it manually:

If you don't want to import listUtil:

rows = 3
cols = 5
grid = []
for r in range(1, rows)
    grid.push [0] * cols
end for

Iterating a 2D array:

for row in grid.indexes
    for col in grid[row].indexes
        // do something with grid[row][col]
    end for
end for

Factory methods on classes

User: What's a good pattern for creating objects with specific initial values in MiniScript?

Assistant: Since MiniScript has no constructors, the idiomatic approach is to define a factory method (often called Make or Create) on the prototype. This method can use new self to create the new instance of the correct type even when it has been subclassed.

Factory method pattern:

Vector = {}
Vector.x = 0
Vector.y = 0

Vector.Make = function(x, y)
    v = new self
    v.x = x
    v.y = y
    return v
end function

Vector.magnitude = function
    return sqrt(self.x^2 + self.y^2)
end function

v = Vector.Make(3, 4)
print v.x              // 3
print v.magnitude      // 5

With default values:

Enemy = {}
Enemy.name = "unknown"
Enemy.hp = 100
Enemy.speed = 1

Enemy.Make = function(name, hp=100, speed=1)
    e = new self
    e.name = name
    e.hp = hp
    e.speed = speed
    return e
end function

goblin = Enemy.Make("Goblin", 30, 2)
dragon = Enemy.Make("Dragon", 500)

Why not just set properties after new?

You can, but a factory method is cleaner when you have multiple properties to initialize, and it keeps the creation logic in one place:

// Without factory method — works but verbose:
goblin = new Enemy
goblin.name = "Goblin"
goblin.hp = 30
goblin.speed = 2

// With factory method — clean and concise:
goblin = Enemy.Make("Goblin", 30, 2)

Naming convention: Make is the most common name for factory methods in MiniScript, but Create, Init, or any clear name works. (By convention, methods intended to be invoked on the prototype, rather than on an instance, are capitalized.)

Debugging infinite loops

User: My MiniScript program is stuck in an infinite loop. How do I figure out what's wrong?

Assistant: Here's a systematic approach to finding and fixing infinite loops:

1. Stop the program: In Mini Micro, press Ctrl+C to break out of a running program.

2. Add debug prints: Insert print statements inside the loop to see what's happening:

while someCondition
    print "loop: x=" + x + " y=" + y   // ADD THIS
    // ... rest of loop
end while

This shows you the values each iteration so you can spot why the exit condition is never met.

3. Common causes:

Forgetting to update the loop variable:

// BUG: i never changes!
i = 0
while i < 10
    print i
    // forgot: i += 1
end while

Updating the wrong variable (scope issue):

count = 0
decrement = function
    count = count - 1   // creates a LOCAL count, doesn't change outer!
end function

while count < 10
    decrement    // doesn't actually decrement outer count
end while

Fix: use outer.count in the function.

Condition can never become false:

x = 10
while x != 0
    x -= 3   // x goes 10, 7, 4, 1, -2, -5... never exactly 0!
end while

Fix: use while x > 0 instead of while x != 0.

Off-by-one with range: If you're not in an infinite loop but getting unexpected behavior, remember range is inclusive — range(0, n) produces n+1 values.

4. Use yield in long loops: Even if your loop is correct, adding yield ensures the display updates and runs at a steady speed:

while processing
    yield
    // heavy work here
end while

Turtle graphics

User: How do I use t graphics in Mini Micro?

Assistant: Mini Micro includes a t graphics module. Import it to get started:

import "turtle"
t = new Turtle  // create a drawing t

// Move forward and turn, four times, making a square
t.penDown
t.forward 100
t.right 90
t.forward 100
t.right 90
t.forward 100
t.right 90
t.forward 100

Key turtle commands:

Assuming you have imported "turtle" and done t = new Turtle:

• t.forward n — move forward n pixels
• t.backward n — move backward n pixels
• t.right degrees — turn right
• t.left degrees — turn left
• t.penDown = false — stop drawing
• t.penDown = true — resume drawing
• t.color = color.red — set the pen color
• t.penSize = 3 — set the pen width
• t.goTo x, y — move to a specific position (while drawing)
• t.jumpTo x, y — move to a specific position (without drawing)
• t.heading = 90 — set the direction (0=right, 90=up)

Drawing a circle:

import "turtle"
t = new Turtle
for i in range(1, 360)
    t.forward 2
    t.right 1
end for

Drawing a star:

import "turtle"
t = new Turtle
t.color = color.yellow
for i in range(1, 5)
    t.forward 150
    t.right 144
end for

Drawing a spiral:

import "turtle"
t = new Turtle
t.color = color.lime
for i in range(1, 200)
    t.forward i
    t.right 91
end for

The turtlre starts at the center of the screen (480, 320), facing right. It draws on the gfx layer.

Recursive drawing algorithms

User: How do I draw fractal-like shapes using recursion in Mini Micro?

Assistant: Combine turtle graphics with recursion to draw fractal patterns. Here are a couple of examples:

Koch snowflake curve:

import "turtle"
t = new Turtle

kochCurve = function(length, depth)
    if depth == 0 then
        t.forward length
    else
        kochCurve length/3, depth-1
        t.left 60
        kochCurve length/3, depth-1
        t.right 120
        kochCurve length/3, depth-1
        t.left 60
        kochCurve length/3, depth-1
    end if
end function

// Draw a Koch snowflake (3 sides)
t.jumpTo 200, 500
t.color = color.aqua

for i in range(1, 3)
    kochCurve 400, 3
    t.right 120
end for

Recursive tree:

import "turtle"
t = new Turtle

drawTree = function(branchLen, depth)
    if depth == 0 then return
    t.penSize = depth
    t.color = color.rgb(50, depth*30, 0)
    t.forward branchLen
    t.left 30
    drawTree branchLen * 0.7, depth - 1
    t.right 60
    drawTree branchLen * 0.7, depth - 1
    t.left 30
    t.backward branchLen
end function

t.jumpTo 480, 50
t.heading = 90
drawTree 120, 10

Sierpinski triangle:

import "turtle"
t = new Turtle

sierpinski = function(length, depth)
    if depth == 0 then
        for i in range(1, 3)
            t.forward length
            t.left 120
        end for
    else
        sierpinski length/2, depth-1
        t.forward length/2
        sierpinski length/2, depth-1
        t.backward length/2
        t.left 60
        t.forward length/2
        t.right 60
        sierpinski length/2, depth-1
        t.left 60
        t.backward length/2
        t.right 60
    end if
end function

t.jumpTo 180, 100
t.color = color.lime
sierpinski 500, 6

The key pattern: the recursive function draws a simpler version at smaller scale, calling itself for sub-parts.

Cloning and mutating objects

User: How do I make a copy (clone) of a map and then modify it without affecting the original in MiniScript?

Assistant: Maps, like lists, are reference types in MiniScript. Assigning a map to a new variable doesn't copy it. To make an independent shallow copy, add an empty map to it with +:

original = {"name": "Alice", "age": 30}
clone = original + {}

clone.name = "Bob"
print original.name   // Alice (unaffected)
print clone.name      // Bob

Why original + {}? The + operator on maps merges the right map into the left, producing a new map. Adding {} gives you a fresh copy.

Deep copy for nested maps:

If your map contains lists or other maps, original + {} only makes a shallow copy — nested objects are still shared. For a deep copy:

deepCopyMap = function(m)
    result = {}
    for kv in m
        if kv.value isa map then
            result[kv.key] = deepCopyMap(kv.value)
        else if kv.value isa list then
            result[kv.key] = kv.value[:]
        else
            result[kv.key] = kv.value
        end if
    end for
    return result
end function

original = {"name": "Alice", "scores": [90, 85, 95]}
clone = deepCopyMap(original)
clone.scores.push 100
print original.scores   // [90, 85, 95] (unaffected)
print clone.scores      // [90, 85, 95, 100]

Quick reference:

• Shallow copy of a list: copy = original[:]
• Shallow copy of a map: copy = original + {}
• For simple maps (no nested collections), shallow copy is sufficient

Where to get MiniScript help

User: Where can I go to get help with MiniScript programming or find example code?

Assistant: Here are the best resources for MiniScript help and examples:

Official resources:

• MiniScript website: https://miniscript.org — documentation, tutorials, and reference
• MiniScript wiki: https://miniscript.org/wiki — detailed language reference with examples
• Quick Reference: https://miniscript.org/files/MiniScript-QuickRef.pdf

Community:

• MiniScript Discord: Active community where you can ask questions and share projects
• GitHub: https://github.com/JoeStrout/miniscript — source code, issues, and discussions

Mini Micro specific:

• Mini Micro resources: https://miniscript.org/MiniMicro/#learn
• Mini Micro Cheat Sheet: https://miniscript.org/files/MiniMicro-CheatSheet.pdf
• Built-in demos: Mini Micro comes with example programs in /sys/demo/ — load and study them:

  load "/sys/demo/ticTacToe"
  run
  

Learning tips:

• Start with the Mini Micro Cheat Sheet for basic and APIs
• Explore the /sys/demo/ programs in Mini Micro to see working examples
• The wiki has pages for every built-in function with usage examples
• Use the interactive command line — type expressions directly to experiment

String concatenation and mixing types

User: How do I combine strings and numbers together in MiniScript output?

Assistant: Use the + operator to concatenate strings and numbers. MiniScript automatically converts numbers to strings when you add them to a string:

name = "Alice"
age = 30
print "Hello, " + name + "! You are " + age + " years old."
// Hello, Alice! You are 30 years old.

The key rule: if either side of + is a string, the result is string concatenation. If both sides are numbers, it does addition.

print "Score: " + 42      // Score: 42 (string + number = concatenation)
print 10 + 20              // 30 (number + number = addition)
print "10" + 20            // 1020 (string + number = concatenation)

If you need to explicitly convert a number to a string, use str:

x = 42
s = str(x)
print s        // "42" (but it's a string now)

Use of str gives you explicit control, but usually + handles it automatically. Just make sure the left side of your first + is a string if you want concatenation:

x = 10
y = 20
print x + y             // 30 (both numbers, so addition)
print "" + x + y         // 1020 (starts with string, so concatenation)
print x + " and " + y    // 10 and 20 (string in the middle forces concatenation for the rest)

String operators (subtraction and replication)

User: Can you subtract or multiply strings in MiniScript? What does that do?

Assistant: Yes! MiniScript supports several unusual but useful string operators.

String subtraction (-): Removes the right string from the end of the left string, if it exists.

print "banana" - "na"           // bana (removes "na" from the end)
print "abcabc" - "abc"          // abc (removes "abc")
print "myFile.txt" - ".txt"     // myFile (removes the ".txt" extension)
print "Hello World" - "o"       // Hello World (no change; string does not end in "o"

String multiplication (*): Repeats the string the given number of times:

print "ha" * 3          // hahaha
print "-" * 20          // --------------------
print "abc" * 0         // (empty string)

This is very handy for creating separators, padding, or repeated patterns:

print "=" * 40
print "  Title"
print "=" * 40

String division (/): Cuts a string down, just like multiplying by the inverse of the right-hand side.

print "banana" / 3         // "ba"
print "hello world!" / 2   // "hello "

Order of operations

User: What order does MiniScript evaluate math operators, and how can I change it?

Assistant: MiniScript follows standard mathematical order of operations (precedence), from highest to lowest:

1. ^ — exponentiation (right-to-left)
2. *, /, % — multiplication, division, modulo
3. +, - — addition, subtraction
4. <, >, <=, >=, ==, != — comparisons
5. not — logical negation
6. and — logical AND
7. or — logical OR

Examples:

print 2 + 3 * 4       // 14 (not 20 — multiplication first)
print 10 - 3 + 2       // 9 (left-to-right for same precedence)
print 10 % 3 * 2       // 2 (modulo first: 10%3=1, then 1*2=2)

Use parentheses to override precedence:

print (2 + 3) * 4      // 20
print (10 - 3) + 2      // 9

// More practical example:
average = (a + b + c) / 3

Tip: When in doubt, use parentheses to explicitly group parts of an expression. They make your intent clear even if they're not strictly necessary:

// Both produce the same result, but the second is clearer:
result = a * b + c / d
result = (a * b) + (c / d)

Calling functions with dot syntax

User: What's the difference between len("Hello") and "Hello".len in MiniScript?

Assistant: They do the same thing — both return 5. MiniScript lets you call many built-in functions either way: as a traditional function call or using dot syntax.

s = "Hello"
print len(s)     // 5
print s.len      // 5

The dot syntax (.len) is generally preferred as more idiomatic MiniScript. It reads more naturally and chains well:

// Dot syntax (idiomatic):
myList = [1, 2, 3, 4, 5]
print myList.len       // 5
s = "Hello World"
print s.upper          // HELLO WORLD
print s.upper.indexOf("L")   // 2

// Function syntax (also works):
print len(myList)      // 5
print upper(s)         // HELLO WORLD
print indexOf(upper(s), "L")  // 2

Note that with dot syntax, the value before the dot becomes the "self" argument. So s.indexOf("W") is equivalent to indexOf(s, "W"). This works only for functions where the first parameter is named "self".

This applies to many built-in functions: len, val, str, code, char, indexOf, replace, split, join, upper, lower, trim, hasIndex, remove, push, pop, pull, sort, shuffle, sum, indexes, values, and more.

When you must use function syntax:

For functions that don't operate on a specific value, like rnd, time, or print; and on most numeric functions, like abs, cos, or floor, you use the normal function call syntax:

print floor(3.7)    // 3
print rnd            // random number 0-1

Generating random numbers

User: How do I generate a random integer between 1 and 100 in MiniScript?

Assistant: Use the rnd function with floor, and add one:

n = floor(rnd * 100) + 1
print n   // random integer from 1 to 100

How it works:

• rnd returns a random number from 0 (inclusive) to 1 (exclusive)
• Multiplying by 100 gives a range of 0 to 99.999...
• floor rounds down to the nearest integer, giving 0 to 99
• adding 1 bumps this into the desired range, 1 to 100

General formula for a random integer from a to b:

n = floor(rnd * (b - a + 1)) + a

Examples:

die = floor(rnd * 6) + 1         // 1 to 6 (die roll)
coin = floor(rnd * 2)            // 0 or 1 (coin flip)
percent = floor(rnd * 101)       // 0 to 100

Picking a random element from a list:

List indexing ignores the decimal part, doing floor implicitly. So you can just do:

colors = ["red", "blue", "green", "yellow"]
pick = colors[rnd * colors.len]
print pick   // random color

Other useful rnd patterns:

// Random number with decimal places (e.g., 0.0 to 10.0):
x = rnd * 10

// 50% chance of something:
if rnd < 0.5 then print "heads" else print "tails"

// 20% chance:
if rnd < 0.2 then print "critical hit!"

Including quotation marks in a string

User: How do I include quotation marks inside a MiniScript string?

Assistant: In MiniScript, you include a literal quote mark inside a string by doubling it — use "" inside the string:

print "She said ""hello"" to me."
// Output: She said "hello" to me.

A few more examples:

quote = "The sign read ""DO NOT ENTER""."
print quote
// Output: The sign read "DO NOT ENTER".

dialog = "He asked, ""How are you?"""
print dialog
// Output: He asked, "How are you?"

MiniScript does not use backslash escapes like \" — that's a common mistake if you're coming from Python, JavaScript, or C. The only escape-like mechanism is doubling the quote character.

Special characters:

For other special characters like newlines or tabs, use the char function with the Unicode code point:

newline = char(10)
tab = char(9)
print "Line 1" + newline + "Line 2"
// Output:
// Line 1
// Line 2

print "Col1" + tab + "Col2"
// Output: Col1	Col2

The print command

User: How do I display output in MiniScript?

Assistant: Use the print command:

print "Hello, world!"
print 42
print 2 + 3    // prints 5

print outputs a value followed by a newline. It can print any type:

print [1, 2, 3]                  // [1, 2, 3]
print {"name": "Alice"}          // {"name": "Alice"}
print null                       // null
print true                       // 1

Printing without a newline: print takes a second parameter, which is the separator to print after the given string. By default this is a newline, but you can specify anything else, including an empty string if you just want to suppress the newline.

for i in range(1, 5)
    print i, ""
end for
print "!"
// Output: 12345!

Printing multiple values: Concatenate them with +:

name = "Alice"
score = 95
print name + " scored " + score + " points"
// Alice scored 95 points

Or, if you need to use multiple print calls (e.g. because you are iterating over some collection), use the second parameter as in the previous example.

Note: Parentheses are not needed (and discouraged) around the argument to print:

print "Hello"      // good (idiomatic)
print("Hello")     // works, but unnecessary parens

Case sensitivity

User: I wrote Print "hello" and got an "Undefined Identifier" error. What went wrong?

Assistant: MiniScript is case-sensitive. The correct command is print (all lowercase), not Print:

Print "hello"   // ERROR: Undefined Identifier: 'Print'
print "hello"   // correct!

This applies to all keywords and built-in functions in MiniScript — they are all lowercase:

// Wrong (capital letters):
For i In Range(1, 5)    // errors!
If x > 5 Then           // errors!
While True              // errors!

// Correct (all lowercase):
for i in range(1, 5)    // good
if x > 5 then           // good
while true              // good

The same goes for built-in functions like floor, ceil, abs, rnd, str, val, len, etc. — always lowercase.

Your own variable and function names can use any mix of cases:

myScore = 100       // fine
PlayerName = "Ada"  // fine (but camelCase is more conventional)

If you get an "Undefined Identifier" error, check the capitalization first — it's one of the most common mistakes.

Numbers and exponential notation

User: How do I write very large or very small numbers in MiniScript?

Assistant: MiniScript supports scientific notation using e or E:

bigNum = 3.5e6       // 3,500,000
smallNum = 2.1e-8    // 0.000000021

print bigNum         // 3500000
print smallNum       // 2.1E-08

The e means "times 10 to the power of":

• 1e3 = 1 × 10³ = 1000
• 5e-4 = 5 × 10⁻⁴ = 0.0005
• 6.022e23 = Avogadro's number

Examples:

speedOfLight = 3e8       // 300,000,000 m/s
electronMass = 9.109e-31  // kg
million = 1e6
billion = 1e9

MiniScript uses double-precision floating point numbers, which gives you about 15-17 significant digits and a range of roughly ±1.8e308.

Converting strings with scientific notation:

s = "3.5e6"
print s.val    // 3500000

The val function handles scientific notation in strings automatically.

Strings vs. numbers

User: What's the difference between print 42 and print "42" in MiniScript?

Assistant: Both display 42 on screen, but the values are different types:

• 42 is a number — you can do math with it
• "42" is a string — a sequence of characters

The difference matters when you use operators:

print 42 + 8       // 50 (numeric addition)
print "42" + 8     // 428 (string concatenation)

print 42 * 2       // 84 (multiplication)
print "42" * 2     // 4242 (string replication)

Converting between them:

// String to number:
n = "42".val       // 42 (as a number)
print n + 8        // 50

// Number to string:
s = str(42)        // "42" (as a string)
print s + "!"      // 42!

Checking the type:

print 42 isa number     // 1 (true)
print "42" isa number   // 0 (false)
print "42" isa string   // 1 (true)

This distinction is especially important with input, which always returns a string:

x = input("Enter a number: ")     // x is a STRING
print x + 10                      // concatenates! ("510" if you typed 5)
print x.val + 10                  // adds! (15 if you typed 5)