{"id":22426509,"url":"https://github.com/jesstelford/ldtk-pico8","last_synced_at":"2025-03-27T06:20:36.039Z","repository":{"id":176313926,"uuid":"603613366","full_name":"jesstelford/ldtk-pico8","owner":"jesstelford","description":"Export an LDtk project to a PICO-8 cart.","archived":false,"fork":false,"pushed_at":"2023-06-18T13:51:40.000Z","size":61,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-01T11:26:30.648Z","etag":null,"topics":["game-development","ldtk","pico-8","pico8"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/jesstelford.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2023-02-19T03:28:36.000Z","updated_at":"2024-03-03T16:47:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"b50c89d1-b664-499d-a452-8717a8c47781","html_url":"https://github.com/jesstelford/ldtk-pico8","commit_stats":null,"previous_names":["jesstelford/ldtk-pico8"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jesstelford%2Fldtk-pico8","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jesstelford%2Fldtk-pico8/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jesstelford%2Fldtk-pico8/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jesstelford%2Fldtk-pico8/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jesstelford","download_url":"https://codeload.github.com/jesstelford/ldtk-pico8/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245792346,"owners_count":20672749,"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-development","ldtk","pico-8","pico8"],"created_at":"2024-12-05T19:18:33.828Z","updated_at":"2025-03-27T06:20:36.032Z","avatar_url":"https://github.com/jesstelford.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LDtk PICO-8 tool\n\nExport an [LDtk](https://ldtk.io) project to a PICO-8 cart.\n\n## Why\n\n- LDtk's [Auto Layer Rules](https://ldtk.io/docs/general/auto-layers/) enable\n  \"painting\" map tiles\n- Visual representation of sprite flags\n- High fidelity editor lets you see the whole world at a glance\n\n## Get Started\n\n1. Open the [`pico8-project.ldtk`](pico8-project.ldtk) project file in LDtk,\n   then Tilesets \u003e Source Image \u003e Select your sprite sheet.\n2. Draw some tiles\n3. Run `npx ldtk-pico8 pico8-project.ldtk --output=output.p8`\n4. Run `output.p8` in PICO-8\n\n## Usage\n\n\u003e **Warning**: Will overwrite `output.p8` if it exists.\n\n```\nUsage: npx ldtk-pico8 \u003cLDtk project file\u003e [options]\n\nOptions:\n  -o, --output            Exported PICO-8 cart filename      [string] [required]\n  -s, --overlap-strategy  How to handle overlapping sprite \u0026 map data\n                          [choices: \"error\", \"sprite\", \"map\"] [default: \"error\"]\n      --version           Show version number                          [boolean]\n      --help              Show help                                    [boolean]\n```\n\n\u003e **Note**: Requires `npx`, provided by [Node.js](https://nodejs.org/en/download)\n\n`output.p8` will include your exported map and sprite data, plus basic code for\nviewing the rendered map with arrow keys.\n\n## LDtk Project Setup\n\n### The easy way\n\n1. Download [`pico8-project.ldtk`](pico8-project.ldtk)\n1. Open it in LDtk\n1. Go to Tilesets \u003e Source Image \u003e Select your sprite sheet (up to 128x128px)\n1. Draw some tiles.\n\n### Manual setup\n\nLDtk is much more flexible than PICO-8, so there is some specific limitations /\nsetup that must be done for this tool to work correctly:\n\n1. Create a single level representing the entire PICO-8 map (up to 1024px by\n   512px)\n1. (Optional) Create a single Enum to represent PICO-8 sprite flags (up to 8\n   values.)\n   - To match PICO-8, use this order of colors: red, orange, yellow, green,\n     blue, purple, pink, peach.\n1. Create a single tileset representing the entire PICO-8 sprite set (up to\n   128px by 128px)\n   - Set the \"Tiles layout\" to \"8px\"\n   - If you created an Enum, set it as \"Enum for tile marking\"\n   - To support rendering black within PICO-8, see [Transparency](#transparency)\n     below.\n1. Create as many \"Tile\", \"IntGrid\", or \"Entities\" layers as you like, ensuring:\n   - \"Tileset\" points to the single tileset representing the PICO-8 sprite set\n   - \"Grid size\" is set to \"8px\"\n   - \"Offsets\" and \"Parallax\" are set to \"0px\"\n1. Create as many \"Entities\" as you like, ensuring:\n   - \"Size\" is a multiple of 8\n   - \"Editor visual\" is set to the tileset you created\n\n### Transparency\n\nBy default, PICO-8 treats color `0` as transparent which you may wish to change\nusing the `palt()` command. This is common when your art style uses \"black\noutline\".\n\nInstead of using a non-black color in your tileset, it can be useful to use real\ntransparency (eg in a `.png` file), then have this exporter convert transparent\npixels to the correct color.\n\nTo set which color is used as transparency when exporting, create a Level Custom\nField named `pico8_palt` with a value representing a PICO-8 color number.\n\n## Shared Map \u0026 Sprite data\n\nPICO-8 shares the bottom half of the sprite set with the bottom half of the map.\nSince LDtk has no such limitations, it's possible to accidentally use a sprite\nwhich would overwrite some map data or vice-versa.\n\nIn some cases, you may need more sprites with less map, so you use the shared\narea for sprite data. And in other cases, you need more map than sprites, so you\nuse the shared area for map data.\n\nThe `--overlap-strategy` switch allows you to specify which strategy you wish to\nuse:\n\n- `--overlap-strategy=error` (the default) will throw an error and stop\n  processing if overlapping data is found.\n- `--overlap-strategy=map` will overwrite any sprite data in the shared area\n  with map data.\n- `--overlap-strategy=sprite` will overwrite any map data in the shared area\n  with sprite data.\n\nIt's possible to use the shared area for _both_ map and sprite data by being\ncareful with how you lay out your sprite image and/or your LDtk level data so\nthey don't conflict. Try playing around with leaving empty spaces in the\nsprite/map to accomodate your usage.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjesstelford%2Fldtk-pico8","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjesstelford%2Fldtk-pico8","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjesstelford%2Fldtk-pico8/lists"}