Welcome to CyberBasic! This guide will help you get up and running in minutes.

1. Installation
2. Finding the Executable
3. Your First Program
4. Running Your Code
5. Next Steps

1. Install Prerequisites:

   • MSYS2 with MinGW-w64
   • CMake 3.25 or higher
   • Python 3.10+ with PyYAML

2. Clone and Build:

   git clone https://github.com/CharmingBlaze/cyberbasic.git
   cd cyberbasic
   mkdir build-mingw && cd build-mingw
   cmake -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release ..
   cmake --build .

3. The executable will be at: build-mingw/cyberbasic.exe

1. Install Prerequisites:

   # Linux (Ubuntu/Debian)
   sudo apt install cmake g++ python3 python3-pip
   pip3 install pyyaml
   
   # macOS
   brew install cmake python3
   pip3 install pyyaml

2. Clone and Build:

   git clone https://github.com/CharmingBlaze/cyberbasic.git
   cd cyberbasic
   mkdir build && cd build
   cmake -DCMAKE_BUILD_TYPE=Release ..
   make -j$(nproc)  # Linux
   # or
   make -j$(sysctl -n hw.ncpu)  # macOS

3. The executable will be at: build/cyberbasic

Every push to master kicks off the Build CyberBasic workflow. Open the latest successful run and download:

• cyberbasic-windows – contains cyberbasic.exe, README.md, and docs/HOW_TO_USE.md
• cyberbasic-linux – contains the Linux binary plus documentation

Extract the archive, mark the Linux binary executable (chmod +x cyberbasic), and you’re ready to go.

After building, the executable location depends on your build directory:

• Development build: build/cyberbasic.exe or build-mingw/cyberbasic.exe
• Distribution build (static): build-dist/cyberbasic.exe (recommended for distribution)
• Custom build: Check your build directory

• Default build: build/cyberbasic
• Custom build: Check your build directory

# Windows - Development build
cd build  # or cd build-mingw
.\cyberbasic.exe examples\hello_text.bas

# Windows - Distribution build (static linking, no DLLs)
cd build-dist
.\cyberbasic.exe ..\examples\hello_text.bas

# Linux/macOS
cd build
./cyberbasic ../examples/hello_text.bas

Note: For distribution, use build-dist/cyberbasic.exe which is statically linked and requires no DLL files.

Create a file called hello.bas:

REM My First CyberBasic Program
INITWINDOW(800, 600, "Hello, CyberBasic!")
SETTARGETFPS(60)

WHILE NOT WINDOWSHOULDCLOSE()
    BEGINDRAW()
    CLEARBACKGROUND(30, 30, 50)
    DRAWTEXT("Hello, World!", 300, 280, 40, 255, 255, 255)
    ENDDRAW()
WEND

CLOSEWINDOW()

1. INITWINDOW(800, 600, "Hello, CyberBasic!") - Creates an 800x600 window
2. SETTARGETFPS(60) - Sets target frame rate to 60 FPS
3. WHILE NOT WINDOWSHOULDCLOSE() - Main game loop (runs until window closes)
4. BEGINDRAW() / ENDDRAW() - Start and end drawing frame
5. CLEARBACKGROUND(30, 30, 50) - Clear screen with dark blue color
6. DRAWTEXT(...) - Draw text on screen
7. CLOSEWINDOW() - Clean up and close window

# Windows
cyberbasic.exe your_program.bas

# Linux/macOS
./cyberbasic your_program.bas

# Windows - From project root
.\build-dist\cyberbasic.exe examples\hello_graphics.bas

# Windows - From build directory
cd build-dist
.\cyberbasic.exe ..\examples\hello_graphics.bas

# Linux/macOS - From project root
./build/cyberbasic examples/hello_graphics.bas

# Linux/macOS - From build directory
cd build
./cyberbasic ../examples/hello_graphics.bas

The repository includes 60+ examples in the examples/ directory:

# Windows - Using distribution build (recommended)
.\build-dist\cyberbasic.exe examples\hello_text.bas
.\build-dist\cyberbasic.exe examples\hello_graphics.bas
.\build-dist\cyberbasic.exe examples\simple_pong.bas
.\build-dist\cyberbasic.exe examples\ai_pong.bas
.\build-dist\cyberbasic.exe examples\space_invaders.bas
.\build-dist\cyberbasic.exe examples\model_viewer.bas

# Windows - Using development build
.\build\cyberbasic.exe examples\hello_graphics.bas
.\build\cyberbasic.exe examples\simple_pong.bas

# Linux/macOS
./build/cyberbasic examples/hello_text.bas
./build/cyberbasic examples/hello_graphics.bas
./build/cyberbasic examples/simple_pong.bas
./build/cyberbasic examples/space_invaders.bas

• hello_text.bas - Simple text output
• hello_graphics.bas - Basic graphics demo
• simple_pong.bas - Classic Pong game
• ai_pong.bas - Pong with AI opponent
• space_invaders.bas - Complete Space Invaders game
• model_viewer.bas - 3D model viewer with mouse controls
• collision_demo.bas - Collision detection demo
• minimal_test.bas - Minimal window test

Let's create a simple bouncing ball game:

REM Bouncing Ball Game
INITWINDOW(800, 600, "Bouncing Ball")
SETTARGETFPS(60)

REM Game variables
VAR ballX = 400
VAR ballY = 300
VAR speedX = 5
VAR speedY = 5

REM Game loop
WHILE NOT WINDOWSHOULDCLOSE()
    REM Update ball position
    ballX = ballX + speedX
    ballY = ballY + speedY
    
    REM Bounce off walls
    IF ballX < 0 OR ballX > 790 THEN speedX = -speedX
    IF ballY < 0 OR ballY > 590 THEN speedY = -speedY
    
    REM Draw everything
    BEGINDRAW()
    CLEARBACKGROUND(20, 20, 30)
    DRAWCIRCLE(ballX, ballY, 20, 255, 100, 100)
    ENDDRAW()
WEND

CLOSEWINDOW()

Save this as bouncing_ball.bas and run it!

Now that you're up and running, explore these resources:

• Game Development Guide - Complete guide to making games
• 2D Graphics API Guide - Learn 2D rendering
• 3D Graphics API Guide - Learn 3D rendering
• Quick Reference - Quick syntax reference

• Advanced Features Guide - Enums, dot notation, state machines, ECS
• ECS System Guide - Entity-Component-System architecture
• Modern State System Guide - State machine system

• Check the examples/ directory for 69+ example programs
• Try pong_game.bas for a complete game example
• Explore space_defender.bas for an advanced game

• Distribution Guide - How to distribute your games

• Make sure you're in the correct directory
• Check that the build completed successfully
• Use the full path to the executable

• Check the file path is correct
• Use forward slashes / or double backslashes \\ on Windows
• Make sure the .bas file exists

• Check for error messages in the console
• Make sure INITWINDOW() is called before the game loop
• Verify graphics drivers are up to date

• Use SETTARGETFPS(60) to limit frame rate
• Reduce the number of draw calls
• Optimize your game loop

• Documentation: Check the docs/ folder for comprehensive guides
• Examples: Browse the examples/ directory
• Issues: Open an issue on GitHub
• Community: Join discussions and ask questions

Happy coding! Start simple, experiment, and build amazing games with CyberBasic! 🎮