{"id":13721127,"url":"https://github.com/guitsaru/draco","last_synced_at":"2025-05-07T13:31:50.916Z","repository":{"id":54328385,"uuid":"309955525","full_name":"guitsaru/draco","owner":"guitsaru","description":"An Entity Component System for DragonRuby GTK","archived":false,"fork":false,"pushed_at":"2021-03-03T14:41:42.000Z","size":281,"stargazers_count":47,"open_issues_count":1,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-10-18T15:47:32.790Z","etag":null,"topics":["dragonruby","dragonruby-gtk","dragonrubygtk","game-development"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/guitsaru.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-11-04T09:28:55.000Z","updated_at":"2024-04-10T00:06:36.000Z","dependencies_parsed_at":"2022-08-13T12:10:28.349Z","dependency_job_id":null,"html_url":"https://github.com/guitsaru/draco","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guitsaru%2Fdraco","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guitsaru%2Fdraco/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guitsaru%2Fdraco/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guitsaru%2Fdraco/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guitsaru","download_url":"https://codeload.github.com/guitsaru/draco/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224604781,"owners_count":17339201,"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","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":["dragonruby","dragonruby-gtk","dragonrubygtk","game-development"],"created_at":"2024-08-03T01:01:12.729Z","updated_at":"2024-11-14T10:31:09.750Z","avatar_url":"https://github.com/guitsaru.png","language":"Ruby","funding_links":[],"categories":["Libraries, Frameworks and Wrappers"],"sub_categories":[],"readme":"# Draco\n\nDraco is an Entity Component System for DragonRuby GTK.\n\nAn Entity Component System is an architectural framework that decouples game objects from game logic. An allows you to\nbuild game objects through composition. This allows you to easily share small logic components between different game\nobjects.\n\n## Table of Contents\n\n1. [Sample Application](https://github.com/guitsaru/draco#sample-application)\n2. [Installation](https://github.com/guitsaru/draco#installation)\n3. [Support](https://github.com/guitsaru/draco#support)\n4. [Versioning](https://github.com/guitsaru/draco#versioning)\n5. [Usage](https://github.com/guitsaru/draco#usage)\n    1. [Components](https://github.com/guitsaru/draco#components)\n    2. [Entities](https://github.com/guitsaru/draco#entities)\n    3. [Systems](https://github.com/guitsaru/draco#systems)\n    4. [Worlds](https://github.com/guitsaru/draco#worlds)\n6. [Plugins](https://github.com/guitsaru/draco#plugins)\n7. [Resources](https://github.com/guitsaru/draco#learn-more)\n8. [Commercial License](https://github.com/guitsaru/draco#commercial-license)\n\n## Sample Application\n\nThis repository includes sample applications in the `samples/` directory.\n\n* teeny-tiny - A 20 second space shooter created during the DragonRuby TeenyTiny Game Jam\n* gorillas-basic - A recreation of the gorillas_basic sample game that comes with DragonRuby\n\n### Running the sample application\n\n1. Download the [latest release](https://github.com/guitsaru/draco/archive/main.zip) of this repository.\n2. Create a copy of DragonRuby GTK in a new folder.\n3. Copy the teeny-tiny directory from draco into your new DragonRuby GTK folder. `cp -r draco/samples/ dragonruby/`.\n4. Run them using `./dragonruby teeny-tiny` or `./dragonruby gorillas-basic`.\n\n## Installation\n\n1. Create a `lib` directory inside your game's `app` directory.\n2. Copy `lib/draco.rb` into your new `lib` directory.\n3. In your `main.rb` file, require `app/lib/draco.rb`.\n\n## Support\n\n- Find a bug? [Open an issue](https://github.com/guitsaru/draco/issues).\n- Need help? [Start a Discussion](https://github.com/guitsaru/draco/discussions) or [Join us in Discord: Channel #oss-draco](https://discord.gg/vPUNtwfm).\n\n## Versioning\n\nDraco uses [https://semver.org/].\n\n* Major (X.y.z) - Incremented for any backwards incompatible public API changes.\n* Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.\n* Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.\n\n## Usage\n\n### Components\n\nComponents represent small atomic bits of state. It's better to use many small components than few large components.\nThese can be shared across many different types of game objects.\n\n```ruby\nclass Visible \u003c Draco::Component; end\n```\n\n`Visible` is an example of a tag component. An entity either has it, or it doesn't. We can also associate data with our\ncomponents.\n\n```ruby\nclass Position \u003c Draco::Component\n  attribute :x, default: 0\n  attribute :y, default: 0\nend\n\ncomponent = Position.new\n```\n\nThe component's attributes add a getter and setter on the component for ease of use.\n\n```ruby\ncomponent.x = 110\n\ncomponent.x\n# =\u003e 110\n```\n\n#### Tag Components\n\nThe `Visible` class above is an example of a tag component. These are common enough that we don't necessarily want to\ndefine a bunch of empty component classes. Draco provides a way to generate these classes at runtime.\n\n```ruby\nDraco::Tag(:visible)\n# =\u003e Visible\n```\n\n### Entities\n\nEntities are independant game objects. They consist of a unique id and a list of components.\n\n```ruby\nentity = Draco::Entity.new\nentity.components \u003c\u003c Position.new(x: 50, y: 50)\n```\n\nOften we have types of entities that are reused throughout the game. We can define our own subclass in order to automate creating these entities.\n\n```ruby\nclass Goblin \u003c Draco::Entity\n  component Position, x: 50, y: 50\n  component Tag(:visible)\nend\n\ngoblin = Goblin.new\n```\n\nWe can override the default values for the given components when initializing a new entity.\n\n```ruby\ngoblin = Goblin.new(position: {x: 100, y: 100})\n```\n\nIn order to access the data within our entity's components, the entity has a method named after that component. This is generated based on the\nunderscored name of the component's class (e.g. `MapLayer` would be `map_layer`).\n\n```ruby\ngoblin.position.x\n# =\u003e 100\n```\n\n### Systems\n\nSystems encapsulate all of the logic of your game. The system runs on every tick and it's job is to update the state of the entities.\n\n#### Filters\n\nEach system can set a default filter by passing in a list of components. When the world runs the system, it will set the system's entities to the\nentities that include all of the given components.\n\n```ruby\nclass RenderSpriteSystem \u003c Draco::System\n  filter Tag(:visible), Position, Sprite\n\n  def tick(args)\n    # You can also access the world that called the system.\n    camera = world.filter([Camera]).first\n\n    sprites = entities.select { |e| entity_in_camera?(e, camera) }.map do |entity|\n       {\n        x: entity.position.x - camera.position.x,\n        y: entity.position.y - camera.position.y,\n        w: entity.sprite.w,\n        h: entity.sprite.h,\n        path: entity.sprite.path\n      }\n    end\n\n    args.outputs.sprites \u003c\u003c sprites\n  end\n\n  def entity_in_camera?(entity, camera)\n    camera_rect = {x: camera.x, y: camera.y, w: camera.w, h: camera.h}\n    entity_rect = {x: entity.position.x, y: entity.position.y, w: entity.sprite.w, h: entity.sprite.h}\n\n    entity_rect.intersect_rect?(camera_rect)\n  end\nend\n```\n\n### Worlds\n\nA world keeps track of all current entities and runs all of the systems on every tick.\n\n```ruby\nworld = Draco::World.new\nworld.entities \u003c\u003c goblin\nworld.systems \u003c\u003c RenderSpriteSystem\n\nworld.tick(args)\n```\n\nJust like with entities, we can define a subclassed template for our world.\n\n```ruby\nclass Overworld \u003c Draco::World\n  entity Goblin\n  entity Player, position: { x: 50, y: 50 }, as: :player\n  systems RenderSpriteSystem, InputSystem\nend\n\nworld = Overworld.new\n```\n\n#### Named Entities\n\nIf there are entities that are frequently accessed in our systems, we can give these a name. In the above example, our\nplayer entity has been given the name `player`. We can now access this directly from our world:\n\n```ruby\nworld.player\n```\n\n#### Fetching entities by id\n\nIn some cases you'll want to keep track of entities by their id, such as when you want to keep track of another entity in a component.\n\n```ruby\nentity = Player.new\nentity.id\n# =\u003e 12\n\nworld.entities[12] == entity\n# =\u003e true\n```\n\n## Plugins\n\n* [Draco::Events](https://github.com/guitsaru/draco-events) - On demand system dispatch and component observers.\n* [Draco::Scenes](https://github.com/guitsaru/draco-scenes) - Quickly switch out entities and systems in a world.\n* [Draco::State](https://github.com/guitsaru/draco-state) - Define a set of components on an entity that are mutually exclusive.\n* [Draco::Periodic](https://github.com/guitsaru/draco-periodic) - Make a system run every n ticks instead of every tick.\n\n## Learn More\n\nHere are some good resources to learn about Entity Component Systems\n\n- [Evolve Your Heirarchy](https://cowboyprogramming.com/2007/01/05/evolve-your-heirachy/)\n- [Overwatch Gameplay Architecture and Netcode](https://www.youtube.com/watch?v=W3aieHjyNvw)\n\n## Commercial License\n\nDraco is licensed under AGPL. You can purchase the right to use Draco under the [commercial license](https://github.com/guitsaru/draco/blob/master/docs/COMM-LICENSE).\n\nEach purchase comes with free upgrades for the current major version of Draco.\n\n\u003ca class=\"gumroad-button\" href=\"https://guitsaru.itch.io/draco\" target=\"_blank\"\u003ePurchase Commercial License\u003c/a\u003e\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBefore submitting a pull request, please read the [contribution guidelines](https://github.com/guitsaru/draco/blob/master/.github/contributing.md).\n\nBug reports and pull requests are welcome on GitHub at https://github.com/guitsaru/draco. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/guitsaru/draco/blob/master/CODE_OF_CONDUCT.md).\n\n## Code of Conduct\n\nEveryone interacting in the Draco project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/guitsaru/draco/blob/master/CODE_OF_CONDUCT.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguitsaru%2Fdraco","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguitsaru%2Fdraco","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguitsaru%2Fdraco/lists"}