Gaussian Language (Beta)

Welcome to Gaussian, a scripting language designed for game development experiments! This is currently a beta version, under active development.

Installation / Usage

Currently, Gaussian runs via a bundled interpreter executable.

1. Download: Obtain the appropriate gasrun executable for your operating system (Windows, macOS, Linux).

2. Place in PATH (Optional): For easier use, place the downloaded gasrun executable in a directory included in your system's PATH environment variable.

3. Run a Script: Open your terminal or command prompt, navigate to the directory containing your script, and run it using:

   # If gasrun is in your PATH
   gasrun your_script.gas
   
   # If not in PATH, use the full path
   /path/to/gasrun your_script.gas 
   

Language Basics

Gaussian uses a syntax inspired by languages like JavaScript, Python, and C#.

Comments

// Single-line comments start with //

Variables

Variables are declared using var (mutable) or val (immutable - NOTE: Immutability check for fields is implemented, but re-assignment might not be checked in all contexts yet).

var score = 0;
val playerName = "Hero";
var position; // Initialized to nil

score = score + 10; 
// playerName = "Villain"; // Error if trying to reassign a 'val' field
position = vec2(100, 200); 

Data Types

• Number: Floating-point numbers (e.g., 10, 3.14, -5.5).
• String: Text enclosed in double quotes (e.g., "Hello", "Player Score: "). Supports \" for escaped quotes.
• Boolean: true or false.
• Nil: Represents the absence of a value (nil).
• Array: Ordered list of values (e.g., [1, "two", true, nil]). Accessed with [].
• Map: Key-value pairs (e.g., { name: "Player", health: 100, "pos": vec2(0,0) }). Keys must be numbers or strings. Accessed with [].

Operators

• Arithmetic: +, -, *, / (Numbers)
• Concatenation: + (Strings)
• Comparison: >, >=, <, <= (Numbers)
• Equality: ==, != (Most types)
• Logical: !, and, or (Uses truthiness - false and nil are falsey)

Control Flow

• If/Else:

  if (score > 100) {
      print "High score!";
  } else if (score > 50) {
      print "Good score.";
  } else {
      print "Keep trying!";
  }
  

• While Loop:

  var i = 0;
  while (i < 5) {
      print i;
      i = i + 1;
  }
  

• For Loop (C-style):

  for (var j = 0; j < 3; j = j + 1) {
      print "j = " + j;
  }
  

• Each Loop (Arrays/Strings):

  var names = ["Alice", "Bob", "Charlie"];
  each (name in names) {
      print "Hello, " + name;
  }
  

Functions

function greet(name) {
    print "Hello, " + name + "!";
    return name.length; // Functions can return values
}

var len = greet("Gaussian");
print "Name length: " + len;

Classes & Objects

class Player {
    var x = 0;
    val speed = 5;

    // Initializer (constructor)
    init(startX) {
        this.x = startX; // Access fields using 'this'
        print "Player created at x=" + this.x;
    }

    function move(dx) {
        this.x = this.x + dx * this.speed;
    }
}

var p = Player(50); // Create instance
p.move(10);      // Call method
print "Player position: " + p.x; // Access field

States

States are defined within classes and control behavior or properties.

class Enemy {
    state idle {
        image: "enemy_idle.png" 
        before { print "Enemy idling"; }
    }
    state chasing {
        image: "enemy_chase.png"
        before { print "Enemy chasing!"; }
    }

    init() {
        switch_state idle; // Set initial state
    }

    function startChase() {
        switch_state chasing;
    }
}

var e = Enemy();
e.startChase();

Built-in Functions

Math

• sqrt(n): Square root.
• abs(n): Absolute value.
• random(): Random number between 0.0 (inclusive) and 1.0 (exclusive).
• floor(n): Largest integer less than or equal to n.
• ceil(n): Smallest integer greater than or equal to n.
• round(n): Rounds to the nearest integer.
• sin(radians), cos(radians), tan(radians): Trigonometric functions.
• pow(base, exponent): Base to the power of exponent.
• min(n1, n2, ...): Returns the smallest of two or more numbers.
• max(n1, n2, ...): Returns the largest of two or more numbers.

String

• len(string): Returns the length of the string.
• toUpperCase(string): Returns the uppercase version.
• toLowerCase(string): Returns the lowercase version.
• substring(string, startIndex, endIndex?): Returns substring (endIndex is optional).
• str(value): Converts a value to its string representation.

Type Conversion

• num(value): Converts value (string, boolean) to a number, or nil if conversion fails.

Array

• len(array): Returns the number of elements.
• push(array, element): Adds element to the end (mutates array, returns nil).
• pop(array): Removes and returns the last element (mutates array).

Vector (Vec2 - Represents {x, y})

• vec2(x, y): Creates a new Vec2 object.
• vecAdd(v1, v2): Returns v1 + v2.
• vecSub(v1, v2): Returns v1 - v2.
• vecScale(vector, scalar): Returns vector * scalar.
• vecMag(vector) / vecLength(vector): Returns the magnitude (length).
• vecNorm(vector) / vecNormalize(vector): Returns the normalized (unit) vector.
• vecDot(v1, v2): Returns the dot product.
• Vec2(x, y): Native constructor (can be used like var v = Vec2(1, 2);). Properties are accessed via dot notation (e.g., v.x).

Time

• clock(): Returns the time elapsed since the program started (in seconds).
• wait(seconds): Pauses script execution for the given duration.
• after(seconds) do { ... }: Executes the block once after the duration (does not pause).
• loop every(seconds) do { ... }: Executes the block repeatedly at the given interval (does not pause).
• tick(): (Used internally by engine/framework) Updates timers for after/loop every and returns delta time since last tick.

Misc

• print(value): Prints the string representation of the value to the console.
• Color(r, g, b, a): Native constructor for Color objects (0-255).
• Rectangle(x, y, width, height): Native constructor for Rectangle objects.

Built-in Modules (import)

Import modules to access specific functionality.

import "graphics";
import "input";
import "audio"; 

Graphics (Wraps Raylib)

Provides functions for window management, drawing, textures, etc. Access functions via Graphics.functionName(...).

• Graphics.initWindow(width, height, title)
• Graphics.windowShouldClose()
• Graphics.closeWindow()
• Graphics.beginDrawing(), Graphics.endDrawing()
• Graphics.clearBackground(color)
• Graphics.drawCircle(x, y, radius, color)
• Graphics.drawRectangle(x, y, width, height, color)
• Graphics.drawText(text, x, y, fontSize, color)
• Graphics.loadTexture(path), Graphics.unloadTexture(texture)
• Graphics.drawTexture(texture, x, y, tint)
• Graphics.drawTexturePro(...)
• Graphics.checkCollisionRecs(rec1, rec2)
• Graphics.getFrameTime(), Graphics.setTargetFPS(fps)
• ... and more (reflecting Raylib API)

Input (Wraps Raylib)

Provides functions for keyboard, mouse, and gamepad input. Access via Input.functionName(...).

• Input.isKeyDown(key), Input.isKeyPressed(key)
• Input.getMouseX(), Input.getMouseY()
• Input.isMouseButtonPressed(button)
• Input.checkCollisionPointRec(pointVec2, rectangle)
• Access key codes via Input.Keys.KEY_SPACE, Input.Keys.KEY_UP, etc.
• Access mouse buttons via Input.Mouse.MOUSE_LEFT_BUTTON, etc.

Audio (Wraps Raylib)

Provides functions for loading and playing sounds and music. Access via Audio.functionName(...).

• Audio.loadSound(path), Audio.playSound(sound), Audio.unloadSound(sound)
• Audio.loadMusicStream(path), Audio.playMusicStream(music), Audio.stopMusicStream(music), Audio.updateMusicStream(music), Audio.unloadMusicStream(music)

Feedback / Contributing

This is a beta! Please report any bugs, suggest features, or ask questions by [Specify how users should provide feedback - e.g., opening an issue on GitHub].

AI Integration (Experimental)

Gaussian includes an experimental function to interact with AI models (specifically Google Gemini Pro via its REST API) to get NPC actions or other text generation.

IMPORTANT: API Key Setup

1. Obtain an API key from Google AI Studio (https://aistudio.google.com/app/apikey).
2. Security Warning: For this prototype, the API key must be set as an environment variable named GEMINI_API_KEY on the machine running gasrun.
   • macOS/Linux: export GEMINI_API_KEY="YOUR_API_KEY_HERE"
   • Windows (Command Prompt): set GEMINI_API_KEY=YOUR_API_KEY_HERE
   • Windows (PowerShell): $env:GEMINI_API_KEY="YOUR_API_KEY_HERE"
   • Alternatively, create a .env file in the project root with the line GEMINI_API_KEY=YOUR_API_KEY_HERE (requires dotenv package installed in the project npm install dotenv).
3. DO NOT commit your API key to version control or share it publicly.
4. API usage may incur costs. Monitor your usage on the Google AI platform.

Function:

• ai_get_action(prompt: string) -> string | nil
  • Sends the prompt string to the Gemini Pro model.
  • Returns the generated text response as a string.
  • Returns nil if the API key is missing, a network error occurs, or the API response cannot be parsed.
  • Can throw a RuntimeError if the API returns an error status.

Example Prompt Format:

For NPC actions, structure your prompt clearly:

var npcState = "Status: Healthy. Location: Forest Path. Nearby: Player. Goal: Patrol area.";
var actions = ["ContinuePatrol", "AttackPlayer", "Hide", "LookAround"];
var actionListString = str(actions); // Convert array to string for prompt

var prompt = "You are an NPC guard described by: " + npcState + 
             ". Choose ONE action from the following list: " + actionListString + 
             ". Respond with ONLY the chosen action name.";

var chosenAction = ai_get_action(prompt);

if (chosenAction != nil) {
    print "AI chose action: " + chosenAction;
    // Add logic to perform the chosen action...
} else {
    print "AI action failed.";
}