{"id":36951889,"url":"https://github.com/ken-morel/gama","last_synced_at":"2026-01-17T23:25:05.904Z","repository":{"id":332005479,"uuid":"1042988668","full_name":"ken-morel/gama","owner":"ken-morel","description":"A lightweight C toolkit for safe and simple 2D game development, a cli tool built in v to build projects, featuring immediate mode rendering, minimal built-in physics and a c-api","archived":false,"fork":false,"pushed_at":"2026-01-12T00:53:21.000Z","size":147694,"stargazers_count":5,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2026-01-12T04:53:53.408Z","etag":null,"topics":["c","doxygen","kit-docs","sokol","svelte","sveltekit","v","vlang"],"latest_commit_sha":null,"homepage":"http://gama.rbs.cm","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ken-morel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"kenmorel","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-08-22T23:28:20.000Z","updated_at":"2026-01-11T12:59:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ken-morel/gama","commit_stats":null,"previous_names":["ken-morel/gama"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/ken-morel/gama","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ken-morel%2Fgama","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ken-morel%2Fgama/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ken-morel%2Fgama/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ken-morel%2Fgama/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ken-morel","download_url":"https://codeload.github.com/ken-morel/gama/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ken-morel%2Fgama/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28385632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T12:01:30.995Z","status":"ssl_error","status_checked_at":"2026-01-13T12:00:09.625Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","doxygen","kit-docs","sokol","svelte","sveltekit","v","vlang"],"created_at":"2026-01-13T12:15:38.817Z","updated_at":"2026-01-17T23:25:05.899Z","avatar_url":"https://github.com/ken-morel.png","language":"C","funding_links":["https://ko-fi.com/kenmorel"],"categories":[],"sub_categories":[],"readme":"# Gama: A Simple C Game Engine\n\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\nGama is a lightweight, cross-platform game engine written in C, designed with simplicity and education in mind. It aims to provide a convenient and powerful way for students and beginners to create 2D and 3D games while learning the fundamentals of C programming. The engine prioritizes a minimal, clean C API, control over the game loop, and a stack-first memory philosophy.\n\n\n\n![Gama logo](./gama.svg)\n\n## Philosophy\n\nGama is built on a few core principles to make game development in C more approachable and fun:\n\n-   **You Have Control**: Gama gives you, the developer, full control over the main game loop. The engine provides utilities but stays out of your way.\n-   **Stack First, Heap Less**: The API encourages using stack-allocated data structures to leverage C's automatic memory management and reduce the cognitive load of `malloc` and `free`.\n-   **No Global State**: Gama is designed to avoid global state. You can structure your game into different scenes (as simple C functions), each with its own initialization, objects, and cleanup.\n-   **Immediate Mode**: The 2D rendering API follows an immediate-mode paradigm. You draw shapes directly each frame, which simplifies state management and is perfect for learning.\n\n## Features\n\n### Core Engine\n- **Cross-Platform**: Build and run your games on **Linux**, **Windows**, and the **Web** (via WebAssembly).\n- **Simple C API**: A clean, beginner-friendly C99 API.\n- **Full Game Loop Control**: You own the `main` loop.\n- **Custom Memory Allocator**: A static-pool-based `malloc` implementation, ideal for controlled memory environments like WASM.\n- **Lightweight**: gama installation is less than `30MB`, tcc compiler is less than `100MB`, and `zig cc`  compiler\n  used to build for web less than `200MB`.\n\n### Rendering\n- **2D Immediate-Mode Graphics**: Simple functions to draw primitive shapes like rectangles, circles, lines, and triangles.\n- **2D Sprite Animation**: A complete sprite system with support for sprite sheets and custom animation sequences.\n- **3D Software Rasterizer**: A built-in 3D rendering pipeline that projects 3D models onto a 2D image buffer, complete with lighting and backface culling.\n- **3D Model Loading**: Support for loading `.obj` and `.gltf` 3D models.\n- **Material \u0026 Texture Support**: The 3D pipeline supports basic material properties (diffuse color, shininess) and will use the average color of a texture if one is provided.\n\n### Physics\n- **Built-in 2D Physics Engine**: A simple physics simulation for your 2D games.\n- **Collision Detection**: Supports Circle-vs-Circle, Rectangle-vs-Rectangle, and Circle-vs-Rectangle collision detection.\n- **Physics Bodies**: Create bodies with properties like mass, velocity, acceleration, and restitution (bounciness).\n- **Physics System**: Manage groups of bodies, apply global forces like gravity, and handle collisions automatically.\n\n### UI \u0026 Widgets\n- **Immediate-Mode UI**: A suite of skinnable, immediate-mode UI widgets.\n- **Available Widgets**:\n    - `gmw_button`: An interactive button.\n    - `gmw_switch`: A toggle switch.\n    - `gmw_scale`: A slider for selecting a value in a range.\n    - `gmw_joystick`: A virtual joystick for on-screen controls.\n    - `gmw_frame`: A panel for grouping UI elements.\n- **Theming System**: A simple system for saving and restoring widget themes to easily change UI styles.\n\n### Compiler Toolchain\n- **Zero-Setup on Windows**: On Windows, Gama comes bundled with pre-configured **TCC** and **Zig** compilers. No external downloads or `PATH` configuration needed.\n- **System-Native on Linux**: On Linux, Gama relies on `tcc` and `zig` from your system's package manager, ensuring seamless integration.\n- **`gama dev` for Rapid Development**: Use `gama dev` to instantly run your project with the fast **TCC** compiler. This command also features hot-reloading for rapid iteration.\n- **`gama build` for Optimization**: When ready to create a release build, `gama build` uses the more powerful and optimizing **Zig CC** compiler.\n- **Direct Compiler Access**: Gama provides proxy commands to access the underlying compilers directly, which is great for educational purposes or advanced build scripting. You can use `gama tcc`, `gama zig`, and `gama zcc` as direct replacements for the real commands.\n\n### And More...\n- **Animation Utilities**: A collection of easing functions (`spring`, `ease-in`, `ease-out`) for smooth animations.\n- **Input Handling**: Straightforward functions for checking keyboard and mouse state.\n- **Math \u0026 Debug Libraries**: A custom math library and simple print-based debugging macros.\n\n## Architecture Overview\n\nGama's cross-platform power comes from its flexible backend architecture.\n\n-   **`libvgama`**: The native heart of the engine. Written in V, `libvgama` runs a `sokol`-based game loop, providing a fast and efficient rendering backend via `gg`.\n-   **`gama.js`**: The web backend. This TypeScript runner uses a Web Worker and `SharedArrayBuffer` to run your C code (compiled to WASM) off the main thread for maximum performance in the browser.\n\n## Getting Started\n\nGetting started with Gama is designed to be as simple as possible.\n\n1.  **Download and Install**:\n    -   **Windows**: Download and run the latest `gama-*-windows-setup.exe` from the [releases page](https://github.com/ken-morel/gama/releases). The installer handles everything for you.\n    -   **Linux**: Download the `.deb` or `.pkg.tar.zst` package and install it with your system's package manager. Make sure you also have `tcc` and `zig` installed (`sudo apt install tcc zig` or `sudo pacman -S tcc zig`).\n\n2.  **Create a New Project**:\n    Open a terminal and run:\n    ```bash\n    gama new my_first_game\n    ```\n\n3.  **Run in Development Mode**:\n    Navigate into your new project and start the development server:\n    ```bash\n    cd my_first_game\n    gama dev\n    ```\n    Your game window will appear, and the code will automatically re-compile and re-run whenever you save a change.\n\n4.  **Build for the Web**:\n    To compile your project for a web browser, run:\n    ```bash\n    gama build web\n    ```\n    This will create a `build/web` directory containing all the files needed to run your game on a local web server.\n\n## Development with Gama\n\nHere is a simple example of a \"Hello, World\" application in Gama to demonstrate the basic structure.\n\n```c\n#include \u003cgama.h\u003e\n\nint main() {\n  // Initialize the engine and create a 600x400 window\n  gm_init(600, 400, \"Hello Gama!\");\n\n  // Set a background color\n  gm_background(GM_DARKSLATEGRAY);\n\n  // Main game loop\n  while (gm_yield()) {\n    // gm_yield() handles events, clears the screen, and returns\n    // true as long as the window is open.\n\n    // Draw a red rectangle in the center of the screen\n    gm_draw_rectangle(0, 0, 0.5, 0.3, GM_RED);\n\n    // Draw some text\n    gm_draw_text(0, 0, \"Hello, World!\", \"default-ui\", 0.1, GM_WHITE);\n  }\n\n  // The engine will automatically handle cleanup on exit.\n  return 0;\n}\n```\n## Development on Gama\n\n### Prerequisites\n- **V Compiler**: The `mng` build script is written in V. You will need to install the V compiler from [vlang.io](https://vlang.io).\n- **A C Compiler**: For building `vlibvgama` (e.g., `clang` or `gcc`).\n- **`bun`**: For building `gama.js`.\n- **`unzip`**: The `mng` script uses `unzip` to set up the Zig toolchain for packaging.\n- **Doxygen (Optional)**: For generating reference documentation.\n- **`makensis` (Optional)**: For building the Windows installer.\n- **`nfpm` (Optional)**: For creating `.deb` packages.\n\n### Building and Running\n\nThe project uses two primary scripts for development and packaging, both located at the project root.\n\n-   **`./mng`**: This is a task runner written in V, used for most common development operations. It allows you to build individual components of the Gama ecosystem.\n    -   `./mng build`: Compiles the `gama` CLI tool for all target platforms.\n    -   `./mng runner native`: Builds the `libvgama` native library.\n    -   `./mng runner web`: Builds the `gama.js` web runner.\n    -   `./mng get-zig`: Downloads and sets up the Zig compiler needed for packaging.\n    -   `./mng package`: Creates the final distributable packages (`.deb`, `.tar.zst`, `.exe` installer).\n\n-   **`./all`**: This is a simple shell script that runs the entire build and packaging pipeline from start to finish. It's the easiest way to ensure all components are up-to-date and generate a full release.\n\n## Project Structure\n- `lib/gama/`: Contains all the core C header files for the engine's modules (3D, physics, widgets, etc.).\n- `gama/`: Vlang source code for the main `gama` CLI tool and build logic.\n- `gama.js/`: TypeScript source for the WebAssembly frontend and JS/C interop.\n- `mng`: The main V script used for building, packaging, and managing the project.\n- `all`: The master shell script to build and package everything.\n- `runners/`: Contains the platform-specific code for running Gama applications (e.g., on web or native).\n- `site/`: SvelteKit source code for the official website and documentation portal.\n- `test/`: Contains example projects and test cases for the engine.\n\n## Contributing\nContributions are welcome! Please feel free to submit a pull request or open an issue.\n\nTo contribute to the website or documentation:\n- The website source code is in the `site/` directory.\n- The API reference is generated automatically with Doxygen via the `./mng docs` command.\n\n## License\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fken-morel%2Fgama","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fken-morel%2Fgama","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fken-morel%2Fgama/lists"}