{"id":20947662,"url":"https://github.com/joebrogers/pico-ec","last_synced_at":"2025-05-14T02:30:27.530Z","repository":{"id":109149605,"uuid":"127318728","full_name":"JoebRogers/PICO-EC","owner":"JoebRogers","description":"A tiny scene-entity-component library created for the PICO-8 fantasty console.","archived":false,"fork":false,"pushed_at":"2019-01-05T02:39:45.000Z","size":54,"stargazers_count":50,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-02T09:32:44.457Z","etag":null,"topics":["game","game-2d","game-dev","game-development","game-engine","gamedev","games","lua","lua-library","pico-8","pico8"],"latest_commit_sha":null,"homepage":"https://joebrogers.com/Libraries/PICO-EC/API/1.0/","language":"Lua","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/JoebRogers.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}},"created_at":"2018-03-29T16:32:40.000Z","updated_at":"2024-06-26T06:54:35.000Z","dependencies_parsed_at":"2023-03-10T17:15:24.282Z","dependency_job_id":null,"html_url":"https://github.com/JoebRogers/PICO-EC","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoebRogers%2FPICO-EC","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoebRogers%2FPICO-EC/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoebRogers%2FPICO-EC/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoebRogers%2FPICO-EC/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JoebRogers","download_url":"https://codeload.github.com/JoebRogers/PICO-EC/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225270623,"owners_count":17447635,"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":["game","game-2d","game-dev","game-development","game-engine","gamedev","games","lua","lua-library","pico-8","pico8"],"created_at":"2024-11-19T00:12:33.825Z","updated_at":"2024-11-19T00:12:34.389Z","avatar_url":"https://github.com/JoebRogers.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-brightgreen.svg)](https://github.com/JoebRogers/PICO-EC/graphs/commit-activity) \n[![License](https://img.shields.io/github/license/mashape/apistatus.svg)](https://en.wikipedia.org/wiki/MIT_License) \n[![Ask Me Anything !](https://img.shields.io/badge/Ask%20me-anything-1abc9c.svg)](https://joebrogers.com) \n[![Twitter Follow](https://img.shields.io/twitter/follow/JoebMakesGames.svg?style=social\u0026label=Follow)](https://twitter.com/JoebMakesGames)\n[![Made With PICO-8](https://img.shields.io/badge/Made%20With-PICO--8-ff004d.svg?style=flat\u0026logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAYAAACNiR0NAAAAlUlEQVQ4jWP8v5gBFTxOR%2BVXPfuPwp8SxIjCt%2BBG4TIxUBkMfgNZGIyi0IRmoobZxxeo0rcPocp%2FEEEJ08HvZaobyPj%2FjTpqmLAeJM2EtgMo3MHvZeqnw9X%2FXVHSUdhnP5Qw%2Fc%2B7CUVDS%2BsWFH6QpuyIT4cMT8xQBJI%2B1aHwj1%2F3RgnTVJbrKGH29egxFPWD38tUNxAAun4liexlTtMAAAAASUVORK5CYII%3D)](https://www.lexaloffle.com/pico-8.php)\n\n![PICO-EC](img/logo.png)\n\nPICO-EC aims to provide very basic and simple support for Scenes, Entities and Components within PICO-8.\n\n- The library offers a simple solution to creating custom objects with init, update and draw cycles that\nrun off of the main application states without having to manually maintain and direct their lifecycles.\n\n- Objects can then be manipulated through custom defined behaviours. This allows for easy abstraction of\ngeneric behaviours and properties.\n\n- The library itself doesn't ship with any default behaviours, however a selection of some that I think\nmay be useful, including sprites, animations, transforms and physics can be found here. [To be added]\n\nPICO-EC currently sits at 784 tokens, although this isn't currently particularly optimised. \n\n## Setup\n\nLike any PICO-8 library, integrating this library into your cart is as simple as copy/pasting the source\ninto the top of your code (I recommend the top in order to avoid problems with object ordering).\n\n## Basic Usage\n\nGetting started with PICO-EC aims to be very simple and easy. Here's an example showing how to create\na scene with a default entity added.\n\n```lua\nlocal firstScene = factory.createScene()\nlocal firstEntity = factory.createEntity()\n\nmainScene = firstScene\nmainScene:addEntity(firstEntity)\n```\n\nSimple, right? In order for your scenes to run correctly however, you do of course need to hook them\nup into your main application lifecycle as follows!\n\n```lua\nfunction _init()\n  mainScene:init()\nend\n\nfunction _update()\n  mainScene:update()\nend\n\nfunction _draw()\n  mainScene:draw()\nend\n```\n\nFrom here, the currently active scene will cycle through all of it's added entities and call the \nrelevant lifecycle functions on them. The entities in turn will call these functions on their \nadded components.\n\nNow that's all well and good, but without any behaviours, nothing's actually going to happen, so let's\ncreate some custom behaviours to get a rectangle moving on screen.\n\nI think we're going to want to draw a background rect, and a moveable foreground rect. So thinking logically\nabout separation of behaviours, I think we can separate these into 3 separate components:\n\n- Transform\n- Rect\n- Mover\n\n### Custom Components\n\nCreating a custom component is as simple as defining a new table object and calling a function. Your component\ncan simply hold properties to be manipulated and referenced by other components, or it can override some functions\non the default component to provide some new behvaiours.\n\n```lua\n-- Transform\n_transformComponent = {\n  name = \"Transform\",\n  x = 0,\n  y = 0\n}\n\n-- Rect\n_rectComponent = {\n  name = \"Rect\",\n  transform = nil,\n  w = 0,\n  h = 0,\n  color = 0\n}\n\nfunction _rectComponent:setColor(col)\n  self.color = col\nend\n\nfunction _rectComponent:init()\n  self.transform = self.parent:getComponent(\"Transform\")\nend\n\nfunction _rectComponent:draw()\n  local x = self.transform.x\n  local y = self.transform.y\n  local w = x + self.w\n  local h = y + self.h\n  rectfill(x, y, w, h, self.color)\nend\n\n-- Mover\n_moverComponent = {\n  name = \"Mover\",\n  transform = nil\n}\n\nfunction _moverComponent:init()\n  self.transform = self.parent:getComponent(\"Transform\")\nend\n\nfunction _moverComponent:update()\n  if (btn(0)) self.transform.x -= 1\n  if (btn(1)) self.transform.x += 1\n  if (btn(2)) self.transform.y -= 1\n  if (btn(3)) self.transform.y += 1\nend\n\n```\n\nWith our three primary components now defined, we can bind it all together into our scene down in\nour main section like so:\n\n```lua\n-- Main\n\n-- Create scenes and entities\nlocal movingRectScene = factory.createScene()\nlocal backgroundEnt = factory.createEntity()\nlocal playerEnt = factory.createEntity()\n\n-- Create components for background rect\nbackgroundEnt:addComponent(factory.createComponent(_transformComponent))\nbackgroundEnt:addComponent(factory.createComponent(_rectComponent))\n--Let's set the background's size\nbackgroundEnt:getComponent(\"Rect\"):setSize(128, 128)\n--Let's change the color of the background\nbackgroundEnt:getComponent(\"Rect\"):setColor(5)\n\n-- Create components for player rect\nplayerEnt:addComponent(factory.createComponent(_transformComponent))\nplayerEnt:addComponent(factory.createComponent(_rectComponent))\nplayerEnt:addComponent(factory.createComponent(_moverComponent))\n--Let's set the player's size\nplayerEnt:getComponent(\"Rect\"):setSize(5, 5)\n--Let's change the color of the player\nplayerEnt:getComponent(\"Rect\"):setColor(15)\n\nmainScene = movingRectScene\nmainScene:addEntity(backgroundEnt)\nmainScene:addEntity(playerEnt)\n\nfunction _init()\n  mainScene:init()\nend\n\n\nfunction _update()\n  mainScene:update()\nend\n\n\nfunction _draw()\n  mainScene:draw()\nend\n\n```\n\nLet's take a look at how that runs in the console!\n\n![EC Demo](img/basic-usage-demo.gif)\n\nPerfect! With that finished, you can go off and start writing your own custom\ncomponents, entities and scenes to run drive your games!\n\nWhilst I do believe that this library can be quite verbose for very small PICO-8 projects,\nas your projects reach a higher scale, it can really help to cut down on tokens as your game is\ndriven by many reusable entities and behavioours.\n\n## Examples\n\nYou can find the example code above in the [cart](cart/pico-ec.p8) folder if you want to load it up into the console\nand play around with it!\n\n## Reference\n\nThe API documentation for the library can be viewed [here](https://joebrogers.com/Libraries/PICO-EC/API/1.0/).\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoebrogers%2Fpico-ec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoebrogers%2Fpico-ec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoebrogers%2Fpico-ec/lists"}