{"id":33289527,"url":"https://github.com/captkirk88/zevy-raylib","last_synced_at":"2025-11-17T22:03:32.732Z","repository":{"id":324530371,"uuid":"1097400089","full_name":"captkirk88/zevy-raylib","owner":"captkirk88","description":"zevy-raylib is a Zig integration layer connecting the zevy-ecs with the Raylib game library. It provides a plugin-based architecture for rapid game prototyping with built-in input handling, asset management, GUI components, and embedded resource support.","archived":false,"fork":false,"pushed_at":"2025-11-16T11:39:02.000Z","size":1024,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-16T13:16:10.450Z","etag":null,"topics":["raylib-zig","zevy-ecs","zig","zig-library","zig-package"],"latest_commit_sha":null,"homepage":"","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/captkirk88.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-11-16T05:11:50.000Z","updated_at":"2025-11-16T11:39:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/captkirk88/zevy-raylib","commit_stats":null,"previous_names":["captkirk88/zevy-raylib"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/captkirk88/zevy-raylib","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captkirk88%2Fzevy-raylib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captkirk88%2Fzevy-raylib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captkirk88%2Fzevy-raylib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captkirk88%2Fzevy-raylib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/captkirk88","download_url":"https://codeload.github.com/captkirk88/zevy-raylib/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captkirk88%2Fzevy-raylib/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":284964283,"owners_count":27091965,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-17T02:00:06.431Z","response_time":55,"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":["raylib-zig","zevy-ecs","zig","zig-library","zig-package"],"created_at":"2025-11-17T22:01:32.476Z","updated_at":"2025-11-17T22:03:32.717Z","avatar_url":"https://github.com/captkirk88.png","language":"Zig","funding_links":[],"categories":["Multimedia \u0026 Graphics"],"sub_categories":["Game Development"],"readme":"# Zevy Raylib\n\nZevy Raylib is an integration layer that connects the Zevy ECS with the Raylib game library. It provides input handling, asset loading utilities, GUI components, and a plugin system to register common engine features easily.\n\n[license]: https://img.shields.io/github/license/captkirk88/zevy-raylib?style=for-the-badge\u0026logo=opensourcehardware\u0026label=License\u0026logoColor=C0CAF5\u0026labelColor=414868\u0026color=8c73cc\n\n[![][license]](https://github.com/captkirk88/zevy-raylib/blob/main/LICENSE)\n\n### Requirements\n\n- Zig 0.15.1\n\n### Table of contents\n\n- [Introduction](#introduction)\n- [Quick Start](#quick-start)\n- [Input](#input)\n  - [InputManager](#inputmanager)\n  - [Bindings \u0026 Types](#bindings--types)\n- [IO (Assets)](#io-assets)\n  - [AssetManager](#assetmanager)\n  - [Schemes \u0026 Loaders](#schemes--loaders)\n- [GUI](#gui)\n  - [Components](#components)\n  - [Layout \u0026 Renderer](#layout--renderer)\n  - [Systems](#systems)\n- [Embed](#embed)\n- [Plugins](#plugins)\n  - [RaylibPlugin (app.plugin.zig)](#raylibplugin-appppluginzig)\n  - [RayGuiPlugin (app.plugin.zig)](#rayguiplugin-appppluginzig)\n  - [AssetsPlugin (assets.plugin.zig)](#assetsplugin-assetspluginzig)\n  - [InputPlugin (input.plugin.zig)](#inputplugin-inputpluginzig)\n- [Examples \u0026 Tests](#examples--tests)\n- [Contributing](#contributing)\n\n---\n\n## Introduction\n\nZevy Raylib is a small library that wires the Raylib runtime into a Zevy ECS-based app. It handles window creation, input harvesting, asset management and sets up RayGui-based UI systems over the Zevy scheduler.\n\n---\n\n## Quick Start\n\nAn example application demonstrating manual plugin integration is included. To build and run it:\n\n```bash\nzig build run\n```\n\nThis launches a window showing bouncing colored circles, demonstrating:\n\n- Manual plugin registration (`RaylibPlugin`, `AssetsPlugin`, `InputPlugin`, `RayGuiPlugin`)\n- Custom ECS systems for movement and rendering\n- Entity creation with Position, Velocity, and Sprite components\n- Integration of the Zevy ECS scheduler with Raylib's game loop\n\nThe example source is located in `example_main.zig` at the repository root.\n\n\u003e [!WARNING]\n\u003e This library and its APIs are experimental. They are intended as a convenient integration layer for example apps and prototypes.\n\u003e The API and internal behavior can and will change without backward compatibility guarantees.\n\u003e Tests and cross-platform coverage are limited — treat this as a development-time dependency rather than a production runtime.\n\u003e Please open issues or submit PRs if you rely on features that should be stabilized.\n\nFiles of interest:\n\n- `src/root.zig` — main package root and plugin wiring\n- `src/app.plugin.zig` — Raylib and RayGui plugin implementations\n- `src/assets.plugin.zig` — Adds the asset subsystem to the ECS\n- `src/input.plugin.zig` — Input plugin and system registration\n\n---\n\n## Input\n\nThe input layer provides the following:\n\n- `InputManager` — the main runtime service that polls raylib for input state and dispatches events.\n- `InputBindings` and `InputBinding` — mapping action names to input chords.\n- Input types and helpers (keyboard, mouse, touch, gesture, and gamepads).\n\nFiles and location:\n\n- `src/input/input_manager.zig`\n- `src/input/input_bindings.zig`\n- `src/input/input_types.zig`\n\n### InputManager\n\n`InputManager` is designed to be added to the ECS via the `InputPlugin` and optionally polled directly from systems. It supports event handlers and action checking API:\n\n- `isActionActive(\"action_name\")` — check if action is currently active\n- `wasActionTriggered(\"action_name\")` — check a press event this frame\n- `addEventHandler` — subscribe to input events\n\n### Bindings \u0026 Types\n\nInput bindings, chords, and actions are declared with types located inside the `input` folder. Use the `InputBindings` helper to create action mappings from keyboard/mouse/gamepad/touch inputs.\n\n---\n\n## IO (Assets)\n\nThe IO module provides a powerful `AssetManager\u003cT, Loader\u003e` generator for loading and tracking assets.\n\nKey files:\n\n- `src/io/asset_manager.zig` — generic `AssetManager` implementation\n- `src/io/loaders.zig` — built-in loaders for asset types\n- `src/io/loader.zig` — loader interfaces\n- `src/io/scheme_resolver.zig` — handles scheme parsing and resolving\n\n### AssetManager\n\nUse `AssetManager` to queue asset loads and process them in a separate step. It validates asset paths (supports builtin `embedded://` scheme), manages unload, and stores assets in a string-to-entry map.\n\nUseful methods:\n\n- `loadAsset(file, settings)` — queue asset for asynchronous loading\n- `loadAssetNow(file, settings)` — load asset immediately\n- `process()` — perform a single step of queued loaders\n- `unloadAsset(handle)` — release a loaded asset\n\n### Schemes \u0026 Loaders\n\nThe system supports schemes (for `embedded://` content or custom resolvers) and allows custom loaders via `AssetLoader` and `AssetUnloader` wrappers.\n\n---\n\n## GUI\n\nZevy Raylib exposes a RayGui-based GUI layer tied to the Zevy scheduler.\n\n- `src/gui/ui.zig` — exports `components`, `layout`, `renderer`, and `systems`\n- `src/gui/*` — UI primitives, layout engines (flex, grid, anchor, dock), render systems\n\nThe `RayGuiPlugin` registers a `GuiStage` and several systems:\n\n- uiInputSystem — maps engine input to GUI events\n- flexLayoutSystem / gridLayoutSystem / anchorLayoutSystem / dockLayoutSystem — layout pass\n- uiRenderSystem — draws the UI after the normal draw stage\n\nExamples are available in `src/gui/examples.zig` and unit tests in `src/gui/ui_tests.zig` and `src/gui/ui_render_tests.zig`.\n\n---\n\n## Embed\n\nThe `embed` module exposes helpers to include binary assets in the compiled artifact. See `embed.zig` in `src/builtin`. Use `embedded://` URIs with the asset manager to reference compiled-in assets.\n\n- `src/builtin/embed.zig` — helper utilities\n\n---\n\n## Plugins\n\nZevy Raylib defines several convenience plugins that register and configure services with the Zevy ECS system.\n\n- `src/app.plugin.zig` — Raylib application and RayGui plugin\n- `src/assets.plugin.zig` — assets resource (wraps `io.Assets`)\n- `src/input.plugin.zig` — registers `InputManager` and the input system\n\n### RaylibPlugin (`app.plugin.zig`)\n\nProvides:\n\n- Window creation (`rl.initWindow`) with title, width, height\n- Audio device initialization (`rl.initAudioDevice`)\n- Logging of the window and audio state\n- Cleaning up in `deinit` (close audio and window)\n\nUsage example:\n\n```zig\ntry plugs.add(RaylibPlugin, RaylibPlugin{ .title = \"My App\", .width = 800, .height = 600 });\n```\n\n### RayGuiPlugin (`app.plugin.zig`)\n\nWires RayGui into the Zevy scheduler and adds UI systems to a `GuiStage`. The plugin registers the UI systems and the `uiRenderSystem` into the drawing stage.\n\n### AssetsPlugin (`assets.plugin.zig`)\n\nCreates and registers `io.Assets` in the ECS as a resource so your systems can call `loadAsset` and `process` through the `io` API.\n\n### InputPlugin (`input.plugin.zig`)\n\nRegisters the `InputManager` resource and attaches an input `update` system that polls device state and emits events each frame.\n\n---\n\n## Examples \u0026 Tests\n\n- `src/gui/examples.zig` — GUI usage examples\n- `src/input/tests.zig` — Input unit tests\n- `src/io/*_tests.zig` — IO tests for asset managers and loaders\n\nTo run tests for the package use the workspace-level `zig build test` or per-package tests using `zig build test` inside the package directory.\n\n---\n\n## Contributing\n\n- Follow existing Zig patterns\n- Register new plugins in `src/root.zig` by adding them to `plug()`\n- Add unit tests beside features in the `src/*` directory\n\n### Working with submodules in the `deps/` folder\n\n`zevy_raylib` supports keeping external dependencies inside a `deps/` folder using git submodules. If you (or your CI) have a `.gitmodules` entry for `deps/zevy-ecs`, here are useful commands for fetching and updating the module on Windows PowerShell or a POSIX shell.\n\nClone including submodules (recommended):\n\n```powershell\n# From the repository root\ngit clone --recurse-submodules \u003crepo-url\u003e\n```\n\nIf you already cloned without submodules:\n\n```powershell\ngit submodule update --init --recursive\n```\n\nUpdate an individual submodule to its currently configured branch (reads `.gitmodules` branch, or the checked-out branch in the submodule):\n\n```powershell\n# From repository root\ngit submodule update --remote --merge deps/zevy-ecs\n```\n\nUpdate all submodules to their configured remotes/branches:\n\n```powershell\ngit submodule foreach --recursive 'git fetch --all \u0026\u0026 git merge --ff-only origin/$(git rev-parse --abbrev-ref HEAD)'\n```\n\nIf you want to explicitly pull from a branch in a submodule and commit the gitlink at the top-level repo:\n\n```powershell\ncd deps/zevy-ecs\ngit checkout main\ngit pull origin main\ncd ../..\ngit add deps/zevy-ecs\ngit commit -m \"update deps/zevy-ecs\"\n```\n\nNotes:\n\n- Submodules are tracked by a gitlink in the parent repository: when you update a submodule and commit, the parent repo records the new commit SHA.\n- If you prefer not to use submodules, you can vendor sources under `deps/` manually — but submodules keep history and make updates easier.\n- `git submodule update --remote` will update based on the branch configured in `.gitmodules`. Set a branch via `git submodule set-branch --branch main deps/zevy-ecs` if you want to track a specific branch.\n\n### Zig helper: `update_submodules.zig`\n\nYou can also use the included Zig helper to initialize and update repo submodules. Run it from the `zevy_raylib` folder:\n\n```powershell\nzig run update_submodules.zig\n```\n\nThis runs the same sequence of commands shown above (initialize then update remote for all submodules). The script supports a few flags:\n\n- `--init` — only run `git submodule update --init --recursive`\n- `--remote` — only run `git submodule update --remote --merge --recursive`\n- `--path \u003csubmodule-path\u003e` — update a single submodule path (useful for `deps/zevy-ecs`)\n\n- `--dry-run` — print the `git` commands without running them (useful for review)\n\nExamples:\n\n```powershell\n# Initialize submodules\nzig run update_submodules.zig -- --init\n\n# Update remote merge for all submodules\nzig run update_submodules.zig -- --remote\n\n# Update only the zevy-ecs submodule\nzig run update_submodules.zig -- --remote --path deps/zevy-ecs\n\n# Dry-run example (shows commands but doesn't execute them)\nzig run update_submodules.zig -- --dry-run\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaptkirk88%2Fzevy-raylib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaptkirk88%2Fzevy-raylib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaptkirk88%2Fzevy-raylib/lists"}