{"id":13526408,"url":"https://github.com/qeffects/helium","last_synced_at":"2025-09-03T02:39:36.232Z","repository":{"id":42771960,"uuid":"240363458","full_name":"qeffects/helium","owner":"qeffects","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-01T13:24:27.000Z","size":288,"stargazers_count":112,"open_issues_count":19,"forks_count":9,"subscribers_count":6,"default_branch":"layout","last_synced_at":"2025-05-27T04:02:02.402Z","etag":null,"topics":["gui","helium","love2d","ui"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qeffects.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}},"created_at":"2020-02-13T21:16:09.000Z","updated_at":"2025-05-26T21:09:05.000Z","dependencies_parsed_at":"2025-04-12T08:27:44.347Z","dependency_job_id":null,"html_url":"https://github.com/qeffects/helium","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/qeffects/helium","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qeffects%2Fhelium","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qeffects%2Fhelium/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qeffects%2Fhelium/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qeffects%2Fhelium/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qeffects","download_url":"https://codeload.github.com/qeffects/helium/tar.gz/refs/heads/layout","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qeffects%2Fhelium/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273381828,"owners_count":25095327,"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-09-03T02:00:09.631Z","response_time":76,"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":["gui","helium","love2d","ui"],"created_at":"2024-08-01T06:01:29.242Z","updated_at":"2025-09-03T02:39:36.176Z","avatar_url":"https://github.com/qeffects.png","language":"Lua","funding_links":[],"categories":["UI"],"sub_categories":[],"readme":"![alt text](https://i.imgur.com/ZQBQfsa.png \"Helium\")\r\n# Helium\r\n\r\n![Helium main menu demo](https://j.gifs.com/nRrKmp.gif)\r\n\r\n*a main menu demo made with helium, in action, find [it here](https://github.com/qeffects/main-menu-example)*\r\n\r\n## Basic overview:\r\nHelium is practically more like a UI framework than a fully fledged UI library. \r\nThe idea is to build custom and build simple.\r\n\r\n## Getting started:\r\nLoad helium with `local helium = require 'helium'`\r\nor [check out the pre-configured demo repository](https://github.com/qeffects/helium-demo/)\r\n\r\nThe structure of an element's function is:\r\n\r\n```lua\r\nfunction(param, view)\r\n\t--State/setup/load\r\n\treturn function()\r\n\t\t--Rendering zone\r\n\tend\r\nend\r\n```\r\n\r\nand you can make that function into an element 'factory' like this:\r\n```lua\r\nelementCreator = helium(function(param, view)\r\n\r\n\treturn function()\r\n\r\n\tend\r\nend)\r\n```\r\n\r\nthen you call the element factory with a table of parameters that will get passed to the element and optionally width and height:\r\n\r\n```lua\r\nelement = elementCreator({text = 'foo-bar'}, 100, 20)\r\n```\r\n\r\nthis will create a new instance of the element, and then you can draw it to whatever position you wish (x, y):\r\n\r\n```lua\r\nelement:draw(100, 100)\r\n```\r\n\r\nA quick detour in to 'scenes' which are a collection of elements to be drawn onscreen\r\n\r\nA scene is necessary to start drawing elements, so let's create one like this and set it to active:\r\n\r\n```lua\r\nlocal scene = helium.scene.new(true)\r\nscene:activate()\r\n```\r\n\r\nThen you can draw and update the scene in love's functions:\r\n\r\n```lua\r\nfunction love.update(dt)\r\n\tscene:update(dt)\r\nend\r\n\r\nfunction love.draw()\r\n\t--drawn below the ui element\r\n\tscene:draw()\r\n\t--drawn above the ui elements\r\nend\r\n```\r\n\r\nLet's draw a rectangle with text with the previous skeleton and functions:\r\n\r\n```lua\r\nlocal helium = require 'helium'\r\nlocal scene = helium.scene.new(true)\r\nscene:activate()\r\n\r\nlocal elementCreator = helium(function(param, view)\r\n\r\n\treturn function()\r\n\t\tlove.graphics.setColor(0.3, 0.3, 0.3)\r\n\t\tlove.graphics.rectangle('fill', 0, 0, view.w, view.h)\r\n\t\tlove.graphics.setColor(1, 1, 1)\r\n\t\tlove.graphics.print('hello world')\r\n\tend\r\nend)\r\n\r\nlocal element = elementCreator({text = 'foo-bar'}, 100, 20)\r\n--Needs to be called only once, to draw and then :undraw to stop drawing it onscreen\r\nelement:draw(100, 100)\r\n\r\nfunction love.update(dt)\r\n\tscene:update(dt)\r\nend\r\n\r\nfunction love.draw()\r\n\tscene:draw()\r\nend\r\n```\r\n\r\nAs you can see, you can use regular love.graphics functions inside the element's rendering function, furthermore you don't have to worry about coordinates, as x:0,y:0 inside the element's rendering function will always be the element's onscreen x,y, and the element's dimensions are passed in the view table.\r\n\r\nAlso whatever you pass to the factory here\r\n```lua\r\nlocal element = elementCreator({text = 'foo-bar'}, 100, 20)\r\n```\r\nis accessible in the param table like so:\r\n```lua\r\nlocal elementCreator = helium(function(param, view)\r\n\treturn function()\r\n\t\tlove.graphics.setColor(0.3, 0.3, 0.3)\r\n\t\tlove.graphics.rectangle('fill', 0, 0, view.w, view.h)\r\n\t\tlove.graphics.setColor(1, 1, 1)\r\n\t\tlove.graphics.print(param.text)\r\n\tend\r\nend)\r\n```\r\n\r\n[View the resulting hello world repository here](https://github.com/qeffects/helium-demo/)\r\n\r\nOr continue on to the State and Input guide: [Here](./docs/State-Input-Guide.md)    \r\nIf you are using gamestates, scene guide will be of interest: [Here](./docs/core/Scenes.md)    \r\nFor a more general overview of the whole library: [Module index](./docs/Modules-Index.md)    \r\n\r\nAlso check out the helium configuration values: [Config](./docs/Configuration.md)\r\n\r\nThere's also a main menu example project available here: [Project](https://github.com/qeffects/main-menu-example)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqeffects%2Fhelium","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqeffects%2Fhelium","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqeffects%2Fhelium/lists"}