Game Script Documentation & How-To

Welcome to the Game Script language! This is a custom binary-compiled language designed to make game creation simple and readable.

This workspace comes with three main tools:

1. The Compiler (compiler.py): Translates your human-readable .script files into a machine-readable binary file (.bin).
2. The Virtual Machine (vm.py): Acts as your game engine, reading the binary .bin file and executing the commands in real-time.
3. The IDE (ide.py): A visual code editor with syntax highlighting and a 1-click Run button that compiles and executes your code for you.

🚀 How to Write and Run Code

Option 1: Using the Standalone App (Recommended)

You can run the IDE as a downloadable application without needing to install Python.

1. Locate the standalone executable in the dist/ folder (dist/GameScriptIDE).
2. Run it directly (e.g., ./dist/GameScriptIDE in terminal or double-click it in your file manager).
3. The IDE will open, allowing you to edit and run your scripts with a single click.

Option 2: Using the IDE via Python

1. Open your terminal.
2. Run the command: python3 ide.py
3. A code editor window will open. Write your code in the top window.
4. Click the green ▶ Compile & Run Script button at the top left.
5. The bottom console will display the Virtual Machine's execution output!

Option 3: Using the Terminal Manually

If you prefer to compile and run via the command line:

1. Write your code in game.script.
2. Compile it to binary by running: python3 compiler.py game.script program.bin
3. Execute the compiled binary by running: python3 vm.py program.bin

Option 4: Using the VS Code Extension

For the best development experience, you can use the official Game Script VS Code extension:

1. Open VS Code and go to the Extensions tab (Ctrl+Shift+X).
2. Search for Game Script and install it (or manually install the .vsix file).
3. Open any .gs or .script file to get full syntax highlighting.
4. Click the ▶ (Run) button in the top right corner of the editor to instantly compile and run your game directly inside VS Code!

📖 Language Syntax Guide

Below is a list of all the commands you can use in Game Script. Note: Arguments to commands must be wrapped in double quotes ("like this").

Game & Screen Setup

• Setgame("Engine") - Initializes a built-in game engine. Use "2D", "3D", or "Text".
• Gametype("module_name") - Acts as an import/extension system. Loads additional modules (e.g. "physics", "rpg_kit").
• Gamescreen("height px", "width px") - Sets the window size.
• Settype("types") - Define overall variables.
• gamemap(tilesize["height px","width px","length px"], chunksize["height tiles","width tiles","length tiles"] mapsize["width chunks","length chunks"]) - Initializes the map/chunk rendering.

2D & 3D Specific Engines

• PlayAnim("animation_name") - Plays an animation on the current sprite (2D).
• SetGravity("value") - Sets the global physics gravity (2D/3D).
• SetSkybox("texture.png") - Sets the skybox background (3D).
• SetLight("type", "color") - Adds lighting to the scene (3D).

Text Engine

• PrintLine("text") - Prints a line of text to the console or text engine screen.
• ClearScreen() - Clears all text from the screen.
• AskInput("variable") - Asks the player to type something and saves it.

Camera Controls

• cameraposition("x", "y", "layer") - Sets the camera to a specific static position on the map and layer/Z-index.
• camerafollow("sprite name") - Tells the camera to automatically follow a specific sprite (like the player).
• camerazoom("value") - Sets the zoom level of the camera (e.g. "1.0" is default, "2.0" is zoomed in).

Entities (Sprites)

Sprites are the objects, characters, and items in your game. You spawn one, and the subsequent commands configure it.

• Spawnsprite("sprite name") - Creates a new entity.
• 2Dtexture("texture file.png") - Applies a 2D image to the recently spawned sprite.
• 3Dtexture("texture file.obj") - Applies a 3D model to the recently spawned sprite.
• HitBox("shape", ["height px","width px"]) - Gives the sprite collision.
• position("x", "y") - Sets the (x, y) coordinates. (Position)
• type("type of spriteee") - Sets the category (e.g. "enemy", "player").
• rotation("angle") - Sets rotation.
• layer("layer") - Sets the Z-index or drawing layer.
• destroy("sprite name") - Removes an entity from the game.

Input & Logic

• Keypress("key") - Binds a keyboard key to an action (followed by indented block).
• ontouch("sprite name") - Listens for mobile screen tap/touch on a sprite.
• onswipe("direction") - Listens for swipe gestures (up, down, left, right).
• joystick("true/false") - Enables a virtual on-screen joystick for mobile movement.
• "Variable name"[=,+,-,/,^,sqar](https://github.com/GameScriptTeam/gamescript/blob/HEAD/"value") - Math operations.
• if "Variable name" ["<",">","="] ("value") then - Conditional logic.
• "Variable"[and,or,not,nand,nor]"Variable"="new Variable" - Logic gates.

Movement & Actions

• moveforward("sprite name")("value") - Move forward.
• moveback("sprite name")("value") - Move backward.
• moveleft("sprite name")("value") - Move left.
• moveright("sprite name")("value") - Move right.
• moveup("sprite name")("value") - Move up.
• movedown("sprite name")("value") - Move down.
• wait("value") - wait / Sleep / Pause execution for a number of ticks. (wait)

Text & UI

Spawn text just like you spawn a sprite!

• spawntext("text name") - Creates a UI text element.
• font("font") - Sets the text font.
• text("the text") - The actual words to display.
• size("value") - Font size.
• color("color") - Text color.
• position("x", "y") - UI coordinates on the screen.
• layer("layer") - Sets the Z-index or drawing layer.

Functions

You can bundle blocks of code into reusable functions!

• function("function name") - Defines a new function.
• "code..." - Put your code underneath.
• call("function name") - Runs the function you defined.

🛠️ Example Script

Here is an example of what a simple game setup looks like in game.script:

Setgame("2D")
Gamescreen("800", "600")

Spawnsprite("Player1")
    2Dtexture("hero.png")
    position("100", "100")
    HitBox("square", ["32", "32"])

spawntext("ScoreDisplay")
    text("Score: 0")
    position("10", "10")

function("MovePlayerLoop")
    moveforward("Player1")("5")

call("MovePlayerLoop")

Happy programming in Game Script!