{"id":32398515,"url":"https://github.com/mmoehabb/zigsdl","last_synced_at":"2026-06-13T10:31:43.394Z","repository":{"id":319602391,"uuid":"1005866962","full_name":"mmoehabb/zigsdl","owner":"mmoehabb","description":"A simple framework for developing graphic apps with SDL in zig.","archived":false,"fork":false,"pushed_at":"2026-05-31T17:51:03.000Z","size":3824,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-31T19:22:55.917Z","etag":null,"topics":["framework","game-development","graphics","sdl3","zig-package"],"latest_commit_sha":null,"homepage":"https://mmoehabb.github.io/zigsdl/","language":"Zig","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/mmoehabb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2025-06-21T01:21:07.000Z","updated_at":"2026-05-31T17:51:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"dfce5d52-9cff-4a24-8158-7423a3245d14","html_url":"https://github.com/mmoehabb/zigsdl","commit_stats":null,"previous_names":["mmoehabb/zigsdl"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/mmoehabb/zigsdl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmoehabb%2Fzigsdl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmoehabb%2Fzigsdl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmoehabb%2Fzigsdl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmoehabb%2Fzigsdl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mmoehabb","download_url":"https://codeload.github.com/mmoehabb/zigsdl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmoehabb%2Fzigsdl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34281700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["framework","game-development","graphics","sdl3","zig-package"],"created_at":"2025-10-25T07:59:33.930Z","updated_at":"2026-06-13T10:31:43.389Z","avatar_url":"https://github.com/mmoehabb.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"![cova_icon_v2 1](./splash.svg)\n\n[![Static Badge](https://img.shields.io/badge/v0.16.0(stable)-orange?logo=Zig\u0026logoColor=Orange\u0026label=Zig\u0026labelColor=Orange)](https://ziglang.org/download/)\n[![Static Badge](https://img.shields.io/badge/v0.1.1-blue?logo=GitHub\u0026label=Release)](https://github.com/mmoehabb/zigsdl/releases/tag/0.1.1)\n[![Static Badge](https://img.shields.io/badge/MIT-silver?label=License)](https://github.com/mmoehabb/zigsdl/blob/main/LICENSE)\n\n## About\n\nA relatively easy-to-pick, simple, and straightforward package that developers can use in order to write graphic applications in [Zig](https://ziglang.org/). Just as the name indicates it's build on [SDL3](https://www.libsdl.org/).\n\n- [Install ZigSDL](#install-zigsdl)\n- [Run an Example](#run-an-example)\n- [Extend the Functionality](#extend-the-functionality)\n- [Install SDL3](#install-sdl3)\n- [TODOs](#todos)\n\n## Install ZigSDL\n\nYou can use ZigSDL in your zig project by fetching it as follows:\n\n```bash\nzig fetch --save git+https://github.com/mmoehabb/zigsdl.git\n```\n\nAnd then add it as an import in your exe root module:\n\n```zig\nconst exe = b.addExecutable(.{\n    .name = \"your-project\",\n    .root_module = exe_mod,\n});\n\nconst zigsdl_dep = b.dependency(\"zigsdl\", .{\n    .target = target,\n    .optimize = optimize,\n});\n\nconst zigsdl_mod = zigsdl_dep.module(\"zigsdl\");\n\nexe.root_module.addImport(\"zigsdl\", zigsdl_mod);\n```\n\n\u003e Make sure to install SDL3 first.\n\n## Run an Example\n\nFirst ensure to install SDL3 on your machine, and Zig of course. Choose any example file in the examples directory, and then run it with the following command:\n\n\u003e Note: compatible only with zig versions ^0.16.0\n\n  ```bash\n  zig build example:\u003cexample-filename\u003e\n  ```\n\nFor instance:\n\n  ```bash\n  zig build example:moving-box\n  ```\n\u003e You may also run examples via [luci](https://github.com/mmoehabb/luci). Which is a simple CLI tool that simplifies and unifies running CLI commands across different platforms.\n\n## Extend the Functionality\n\nI bet if you gave the code a look, you'd already know how to extend it and make a functional game with ZigSDL. Here's the moving-box zig file:\n\n```zig\nconst zigsdl = @import(\"zigsdl\");\nconst std = @import(\"std\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    defer {\n        const deinit_status = gpa.deinit();\n        if (deinit_status == .leak) std.debug.panic(\"Memory leak detected!\", .{});\n    }\n\n    // Create a drawable object\n    var rect = zigsdl.drawables.Rect.new(\n        .{ .w = 20, .h = 20, .d = 1 },\n        .{ .g = 255 },\n    );\n    var rect_drawable = rect.toDrawable();\n\n    var obj = zigsdl.modules.Object.init(allocator, .{\n        .name = \"GreenBox\",\n        .position = .{ .x = 20, .y = 20, .z = 1 },\n        .rotation = .{ .x = 0, .y = 0, .z = 0 },\n        .drawable = \u0026rect_drawable,\n    });\n    defer obj.deinit();\n\n    // Add movement script to the object\n    var movement = zigsdl.scripts.Movement{ .velocity = 5, .smooth = true };\n    try obj.addScript(@constCast(\u0026movement.toScript()));\n\n    // Create a scene and add the obj into it\n    var scene = zigsdl.modules.Scene.init(allocator);\n    defer scene.deinit();\n    try scene.addObject(\u0026obj);\n\n    // Create a screen, attach the scene to it, and open it\n    var screen = zigsdl.modules.Screen.init(allocator, .{\n        .title = \"Simple Game\",\n        .width = 320,\n        .height = 320,\n        .rate = 1000 / 60,\n    });\n    defer screen.deinit();\n    screen.setScene(\u0026scene);\n    try screen.open();\n}\n```\n\nYou may add as many objects as you want in the scene, you can easily add different functionalities and behaviour to your objects by adding scripts into them; you may use ZigSDL pre-defined drawables and/or scripts or write your own ones as follows:\n\nThe Rect Drawable:\n\n```zig\nconst zigsdl = @import(\"zigsdl\");\n\npub const Rect = struct {\n    dim: zigsdl.types.common.Dimensions,\n    color: zigsdl.types.common.Color = .{},\n    _draw_strategy: zigsdl.modules.DrawStrategy = zigsdl.modules.DrawStrategy{\n        .draw = draw,\n        .destroy = destroy,\n    },\n\n    pub fn new(dim: zigsdl.types.common.Dimensions, color: zigsdl.types.common.Color) Rect {\n        return Rect{\n            .dim = dim,\n            .color = color,\n        };\n    }\n\n    pub fn toDrawable(self: *Rect) zigsdl.modules.Drawable {\n        return zigsdl.modules.Drawable{\n            .dim = self.dim,\n            .color = self.color,\n            .drawStrategy = \u0026self._draw_strategy,\n        };\n    }\n\n    fn draw(\n        _: *zigsdl.modules.Drawable,\n        _: *const zigsdl.modules.DrawStrategy,\n        renderer: *zigsdl.sdl.SDL_Renderer,\n        p: zigsdl.types.common.Position,\n        _: zigsdl.types.common.Rotation,\n        dim: zigsdl.types.common.Dimensions,\n    ) !void {\n        if (!sdl.c.SDL_RenderFillRect(renderer, \u0026sdl.c.SDL_FRect{\n            .x = p.x,\n            .y = p.y,\n            .w = dim.w,\n            .h = dim.h,\n        })) return error.RenderFailed;\n    }\n\n    fn destroy(\n        _: *zigsdl.modules.Drawable,\n        _: *const zigsdl.modules.DrawStrategy,\n    ) void {}\n};\n```\n\nThe Movement script:\n\n```ZIG\nconst zigsdl = @import(\"zigsdl\");\n\npub const Movement = struct {\n    velocity: f32 = 5,\n    smooth: bool = true,\n\n    _script_strategy: zigsdl.modules.ScriptStrategy = zigsdl.modules.ScriptStrategy{\n        .start = start,\n        .update = update,\n        .end = end,\n    },\n\n    _last_pressed: zigsdl.types.event.Key = .Unknown,\n\n    pub fn toScript(self: *Movement) zigsdl.modules.Script {\n        return modules.Script{ .strategy = \u0026self._script_strategy };\n    }\n\n    fn start(_: *zigsdl.modules.Script, _: *zigsdl.modules.Object) void {}\n\n    fn update(s: *zigsdl.modules.Script, o: *zigsdl.modules.Object) void {\n        const obj = o;\n        const self = @as(*Movement, @constCast(@fieldParentPtr(\"_script_strategy\", s.strategy)));\n        var em = o.*._scene.?.screen.?.em;\n\n        if (self.smooth) {\n            if (em.isKeyDown(.W)) obj.position.y -= self.velocity;\n            if (em.isKeyDown(.S)) obj.position.y += self.velocity;\n            if (em.isKeyDown(.D)) obj.position.x += self.velocity;\n            if (em.isKeyDown(.A)) obj.position.x -= self.velocity;\n            return;\n        }\n\n      // ...\n    }\n\n    fn end(_: *zigsdl.modules.Script, _: *zigsdl.modules.Object) void {}\n};\n```\n\nMoreover, you may access SDL indirectly from ZigSDL, and use SDL facilities in your scripts:\n\n```zig\nconst sdl = @import(\"zigsdl\").sdl;\nsdl.SDL_RenderFillRect(...);\n```\n\n## Install SDL3\n\nThis guide provides brief instructions for installing SDL3 on various operating systems to support projects like `zigsdl`.\n\n\u003e Generated by Grok; with further, manual, modifications.\n\n### Windows\n\n- **Using vcpkg**:\n\n  ```bash\n  vcpkg install sdl3\n  vcpkg install sdl3_ttf\n  vcpkg install sdl3_image\n  ```\n\n- **Manual Installation**:\n\n  - Download the SDL3 development libraries from [libsdl.org](https://www.libsdl.org).\n  - Extract the archive and add the `include` and `lib` directories to your compiler's include and library paths.\n  - Ensure `SDL3.dll` is in your executable's directory or system PATH.\n\n### macOS\n\n- **Using Homebrew**:\n\n  ```bash\n  brew install sdl3\n  brew install sdl3_ttf\n  brew install sdl3_image\n  ```\n\n- **Manual Installation**:\n\n  - Download the SDL3 DMG from [libsdl.org](https://www.libsdl.org).\n  - Copy `SDL3.framework` to `/Library/Frameworks` or your project directory.\n  - Link against the framework in your build configuration.\n\n### Linux (Ubuntu/Debian)\n\n- **Using apt**:\n\n  ```bash\n  sudo apt-get update\n  sudo apt-get install libsdl3-dev\n  sudo apt-get install libsdl3_ttf-dev\n  sudo apt-get install libsdl3_image-dev\n  ```\n\n- **Manual Installation**:\n\n  1. Install SDL3\n    ```bash\n    wget https://github.com/libsdl-org/SDL/releases/download/release-3.2.26/SDL3-3.2.26.tar.gz\n    tar -xf SDL3-3.2.26.tar.gz\n    mkdir ./SDL3-3.2.26/build\n    cd ./SDL3-3.2.26/build\n    cmake ..\n    cmake --build . --parallel $(nproc)\n    sudo cmake --install .\n  ```\n\n  2. Install SDL3_ttf\n    ```bash\n    wget https://github.com/libsdl-org/SDL_ttf/releases/download/release-3.2.2/SDL3_ttf-3.2.2.tar.gz\n    tar -xf SDL3_ttf-3.2.2.tar.gz\n    mkdir ./SDL3_ttf-3.2.2/build\n    cd ./SDL3_ttf-3.2.2/build\n    cmake ..\n    cmake --build . --parallel $(nproc)\n    sudo cmake --install .\n  ```\n\n  3. Install SDL3_image\n    ```bash\n    wget https://github.com/libsdl-org/SDL_image/releases/download/release-3.2.4/SDL3_image-3.2.4.tar.gz\n    tar -xf SDL3_image-3.2.4.tar.gz\n    mkdir ./SDL3_image-3.2.4/build\n    cd ./SDL3_image-3.2.4/build\n    cmake ..\n    cmake --build . --parallel $(nproc)\n    sudo cmake --install .\n  ```\n\n### Linux (Fedora)\n\n- **Using dnf**:\n\n  ```bash\n  sudo dnf install SDL3-devel\n  sudo dnf install SDL3_ttf-devel\n  sudo dnf install SDL3_image-devel\n  ```\n\n### Linux (Arch)\n\n- **Using paru**:\n\n  ```bash\n  paru -S sdl3\n  paru -S sdl3_ttf\n  paru -S sdl3_image\n  ```\n\n### Verifying Installation\n\n- Run `pkg-config --libs --cflags sdl3` to check if SDL3 is correctly installed and accessible.\n- Ensure your build system (e.g., Zig) can find SDL3 by linking with `-lSDL3`.\n\nFor detailed instructions or troubleshooting, visit the [SDL3 documentation](https://wiki.libsdl.org/SDL3/Installation).\n\n\n## TODOs\n\n### Version 0.2.0\n\n#### Features\n- [x] Add loop, pause and volume settings in the AudioPlayer.\n- [x] Make scenes behave like cameras; they can zoom in and out, and move in the four directions.\n\n#### Drawables\n- [ ] Implement a drawable for each common geometric shape.\n- [ ] Implement interactive UI drawables: Button, TextInput, Select, and Checkbox.\n- [x] Implement SVG Drawable.\n\n#### Refactor\n- [ ] Improve _getObjectByName_ \u0026 _getObjectsByTag_ methods in the _scene_ component. \\\nBy storing all objects in hash-tables rather than exhaustively searching for each required \\\nobject by its tag or name. Be aware that each object being added in the tree (calling _addChild_ \\\nmethod from any inner child object) should also update the scene state.\n\n#### Scripts\n- [ ] Implement _Rigidbody_ script; it should, at minimum, specify the mass of the object, detect collisions, and apply gravity.\n- [ ] Implement _Collision_ script; any two objects with this script, and one of them is a rigid-body, they shall not overlap.\n- [ ] Implement AudioSource and AudioListener scripts. The general idea is that whenever an AudioSource \\\ncommence to play an audio, it searches for an AudioListener in the same scene. Once it find one, it plays \\\nthe audio with the volumes of its channels twisted according to the distance between the two objects (one \\\ncarries the source, and another carries the listener).\n- [ ] Write Animation and Animator scripts.\n\n#### Examples\n- [x] Write SVG Example.\n- [ ] Write MainMenu/UI Example.\n- [ ] Develop a [Pong game](https://www.ponggame.org/).\n- [ ] Develop a Sokoban game.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmoehabb%2Fzigsdl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmmoehabb%2Fzigsdl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmoehabb%2Fzigsdl/lists"}