{"id":18495100,"url":"https://github.com/notpeter/playdate-luacats","last_synced_at":"2025-04-09T12:08:17.724Z","repository":{"id":186370202,"uuid":"675072972","full_name":"notpeter/playdate-luacats","owner":"notpeter","description":"LuaCATS for Panic PlaydateSDK API","archived":false,"fork":false,"pushed_at":"2025-04-01T14:24:48.000Z","size":340,"stargazers_count":89,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-02T11:02:04.332Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/notpeter.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE-APACHE","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},"funding":{"github":"notpeter"}},"created_at":"2023-08-05T17:21:17.000Z","updated_at":"2025-04-01T14:24:13.000Z","dependencies_parsed_at":"2023-10-01T16:23:17.191Z","dependency_job_id":"fcca6605-2d55-4a4a-b2f1-4c2e3bdfe33f","html_url":"https://github.com/notpeter/playdate-luacats","commit_stats":null,"previous_names":["notpeter/playdate-luacats"],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notpeter%2Fplaydate-luacats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notpeter%2Fplaydate-luacats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notpeter%2Fplaydate-luacats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notpeter%2Fplaydate-luacats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/notpeter","download_url":"https://codeload.github.com/notpeter/playdate-luacats/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248036067,"owners_count":21037092,"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":[],"created_at":"2024-11-06T13:23:28.801Z","updated_at":"2025-04-09T12:08:17.698Z","avatar_url":"https://github.com/notpeter.png","language":"Lua","funding_links":["https://github.com/sponsors/notpeter","https://github.com/sponsors/notpeter/"],"categories":[],"sub_categories":[],"readme":"# LuaCATS for Panic PlaydateSDK\n\n\u003cimg width=\"359\" alt=\"AI Generated Image of cat holding a game controller\" src=\"https://github.com/notpeter/playdate-luacats/assets/145113/4be26c10-42b2-4139-a926-31fffcf97f59\"\u003e\n\n## Unofficial Definitions for the Panic Playdate Lua SDK.\n\nText \u0026 API Copyright (c) Panic Inc, [PlaydateSDK License 1.0](https://play.date/dev/sdk-license/)\n\nTypes and everything else Copyright (c) Peter Tripp,\nunder the Apache License, Version 2.0 or the MIT license at your option.\n\n## LuaCATS? What's that.\n\nLuaCATS stands for \"Lua Comment And Type System\", which is the system used by [Sumneko](https://github.com/sumneko)'s\n[Lua Language Server](https://github.com/LuaLS/lua-language-server) for the\n[sumneko.lua VSCode extension](https://marketplace.visualstudio.com/items?itemName=sumneko.lua).\n\nLuaCATS is method to provide machine readable\n[Lua Type Annotations](https://github.com/LuaLS/lua-language-server/wiki/Annotations#deprecated)\nand comments enabling inline autocompletion and linting suggestions in your IDE. Super nifty!\n\n![image](https://github.com/notpeter/playdate-luacats/assets/145113/1ce0e9c1-46ff-4b48-8e3d-c4b2cb519d35)\n\n## How do I use it?\n\n1. Clone this repo somewhere:\n\n```\ncd ~/code/\ngit clone https://github.com/notpeter/playdate-luacats\n```\n\n2. Add the following to `.luarc.json` in your workspace and\n   edit `workspace.library` to reflect where you cloned playdate-luacats\n\n```\n{\n    \"$schema\": \"https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json\",\n    \"diagnostics.globals\": [\"import\"],\n    \"diagnostics.severity\": {\n        \"duplicate-set-field\": \"Hint\"\n    },\n    \"format.defaultConfig\": {\n        \"indent_style\": \"space\",\n        \"indent_size\": \"4\"\n    },\n    \"runtime.builtin\": {\n        \"io\": \"disable\",\n        \"os\": \"disable\",\n        \"package\": \"disable\"\n    },\n    \"runtime.nonstandardSymbol\": [\"+=\", \"-=\", \"*=\", \"/=\", \"//=\", \"%=\", \"\u003c\u003c=\", \"\u003e\u003e=\", \"\u0026=\", \"|=\", \"^=\"],\n    \"runtime.version\": \"Lua 5.4\",\n    \"workspace.library\": [\n        \"/Users/peter/code/playdate-luacats\"\n    ]\n}\n```\n\n3. Enable LuaLS (Lua Language Server) support for your editor:\n\n| Editor  | Instructions                                    | Link                                                                           |\n| ------- | ----------------------------------------------- | ------------------------------------------------------------------------------ |\n| VSCode  | cmd+shift+p \"install extensions\", \"sumneko.lua\" | [sumneko.lua](https://marketplace.visualstudio.com/items?itemName=sumneko.lua) |\n| NeoVim  | `require'lspconfig'.lua_ls.setup{}` in config   | [LuaLS NeoVim Install](https://luals.github.io/#neovim-install)                |\n| Sublime | cmd\\_+shift+p \"install package\", \"LSP-lua\"      | [LSP-Lua Package](https://github.com/sublimelsp/LSP-lua/)                      |\n| Zed     | n/a (LuaLS is built in)                         |                                                                                |\n\n4. Close and re-open your editor; wait 5-10 seconds for LuaLS to initialize.\n\n5. Hover over code or start typing `playdate.` and you'll get suggestions.\n\n## Alternative Usage\n\nIf you would like a minimal set of API definitions that does not include\nthe English function annotations from Playdate SDK docs,\nyou can use this minimal [stub.lua](https://github.com/notpeter/playdate-docdef/blob/main/stub.lua) from\nthe [notpeter/playdate-docdef repo](https://github.com/notpeter/playdate-docdef/) instead of the\nfully annotated [stub.lua](library/stub.lua) in this repo.\n\n## What does it look like\n\n\u003cimg width=\"850\" alt=\"VSCode Screenshot showing inline PlaydateSDK API documentation\" src=\"https://github.com/notpeter/playdate-luacats/assets/145113/55524a57-ea39-44b3-b792-edca2ce582c2\"\u003e\n\n## Where does this come from?\n\n- Types are defined in\n  [notpeter/playdate-docdef/playdate.luars](https://github.com/notpeter/playdate-docdef/blob/main/playdate.luars)\n- We scrape [Lua PlayDateSDK \"Inside Playdate\" HTML Documentation](https://sdk.play.date/)\n- Then generate [stub.lua](library/stub.lua) with LuaCATS annotations.\n\n## Updates?\n\nWork in progress. Currently just do a `git pull` periodically in your local clone.\n\nReleases [are tagged](https://github.com/notpeter/playdate-luacats/tags) and\nyou could [subscribe to an Atom XML Feed](https://github.com/notpeter/playdate-luacats/tags.atom)\nlike it's 2005.\n\nSee: [CHANGELOG.md](CHANGELOG.md).\n\n## Giving Thanks\n\nIf you find this software useful, please consider:\n\n1. [Sponsoring me on GitHub](https://github.com/sponsors/notpeter/)\n2. [Purchasing something from my Itch Store](https://notpeter.itch.io)\n3. Sending me free copies of the Playdate games you build.\n\n## Why are your types different than the docs?\n\ntldr: Our types are `_Image` and `_Sprite` instead of `playdate.graphics.{image,sprite}`.\n\nPanic decided to make their type names match the location in the\nglobal namespace `playdate` table where they organized the code.\nThis makes it impossible to differentiate between the global object\n`playdate.graphics.image` and a instance of type `playdate.graphics.image`.\n\nBoth have a bunch of functions and constants attached like `.copy()` and\n`.draw(self, x, y, flip)` and `.kDitherTypeNone`,\nbut only the image instance has `.width`, `.height`\nattributes. Without distinct types, our IDE (via LuaLS) can't tell that\none of these calls will fail at runtime while the other is fine:\n\n```lua\nxpos = playdate.graphics.image.width + 1\nxpos = playdate.graphics.image.new(64, 64).width + 1\n```\n\nWe create short names Types like `_Image`\nwith instance attributes (e.g. `.width`, `.height`)\nand inherit everything else from their parent (e.g. `playdate.graphics.image`).\nWe prefix with \"\\_\" to avoid conflicts.\n\n## Anything else I need to know?\n\n### PlaydateSDK `CoreLibs/Object.lua` classes\n\nIf you are creating class objects via the `class()` function\nyou'll want to describe your class to LuaLS and let it know\nit's been added to the global namespace.\n\nFor example here's a simple class:\n\n```lua\nclass(\"FillSprite\").extends(playdate.graphics.sprite)\n\nfunction FillSprite:init(w, h, color)\n\tlocal img = playdate.graphics.image.new(w, h, color)\n    FillSprite.super.init(self, img)\nend\n\nlocal ts = FillSprite(64, 64 playdate.graphics.kColorBlack)\n```\n\nWhich could be annotated like so:\n\n```lua\n---@class FillSprite: _Sprite\n---@field color: integer\n---@overload fun(w: integer, h:integer, color:integer): FillSprite\nFillSprite = class(\"FillSprite\").extends(playdate.graphics.sprite) or FillSprite\n\nfunction FillSprite:init(w, h, color)\n\tlocal img = playdate.graphics.image.new(w, h, color)\n    FillSprite.super.init(self, img)\n\tself.color = color\nend\n\nlocal ts = FillSprite(64, 64 playdate.graphics.kColorBlack)\n```\n\nThe `FillSprite = [...] or FillSprite` becomes a no-op because\n`class().extends()`\n[returns nil](https://devforum.play.date/t/trivial-object-improvements/13976/2)\nbut does set `G_[\"FillSprite\"]` so we end of up with\n`FillSprite = nil or FillSprite`, a no-op.\n\nThe `@overload` defines a signature for when the name `FillSprite`\nis invoked as a function (via `__call` in it's metatable). With\nObject.lua class objects this should match the signature\nof the `:init` constructor with the a return type\nof the class instance object.\n\n## List of types\n\nThese names do not exist at runtime and are only used by LuaLS.\n\n| playdate-luacats      | Offical Docs                        |\n| --------------------- | ----------------------------------- |\n| \\_AffineTransform     | playdate.geometry.affineTransform   |\n| \\_AnimationLoop       | playdate.graphics.animation.loop    |\n| \\_Animator            | playdate.graphics.animator          |\n| \\_Arc                 | playdate.geometry.arc               |\n| \\_BitCrusher          | playdate.sound.bitcrusher           |\n| \\_Blinker             | playdate.graphics.animation.blinker |\n| \\_Channel             | playdate.sound.channel              |\n| \\_ControlSignal       | playdate.sound.controlsignal        |\n| \\_DelayLine           | playdate.sound.delayline            |\n| \\_DelayLineTap        | playdate.sound.delaylinetap         |\n| \\_Envelope            | playdate.sound.envelope             |\n| \\_File                | playdate.file.file                  |\n| \\_FilePlayer          | playdate.sound.fileplayer           |\n| \\_Font                | playdate.graphics.font              |\n| \\_FrameTimer          | playdate.frameTimer                 |\n| \\_GridView            | playdate.ui.gridview                |\n| \\_Image               | playdate.graphics.image             |\n| \\_ImageTable          | playdate.graphics.imagetable        |\n| \\_Instrument          | playdate.sound.instrument           |\n| \\_LFO                 | playdate.sound.lfo                  |\n| \\_LineSegment         | playdate.geometry.lineSegment       |\n| \\_Menu                | playdate.menu                       |\n| \\_MenuItem            | playdate.menu.item                  |\n| \\_NineSlice           | playdate.graphics.nineSlice         |\n| \\_OnePoleFilter       | playdate.sound.onepolefilter        |\n| \\_OverDrive           | playdate.sound.overdrive            |\n| \\_PathFinderGraph     | playdate.pathfinder.graph           |\n| \\_PathFinderNode      | playdate.pathfinder.node            |\n| \\_Point               | playdate.geometry.point             |\n| \\_Polygon             | playdate.geometry.polygon           |\n| \\_Rect                | playdate.geometry.rect              |\n| \\_RingMod             | playdate.sound.ringmod              |\n| \\_Sample              | playdate.sound.sample               |\n| \\_SamplePlayer        | playdate.sound.sampleplayer         |\n| \\_Sequence            | playdate.sound.sequence             |\n| \\_Signal              | playdate.sound.signal               |\n| \\_Size                | playdate.geometry.size              |\n| \\_SoundEffect         | playdate.sound.effect               |\n| \\_Sprite              | playdate.graphics.sprite            |\n| \\_Synth               | playdate.sound.synth                |\n| \\_TileMap             | playdate.graphics.tilemap           |\n| \\_Timer               | playdate.timer                      |\n| \\_Track               | playdate.sound.track                |\n| \\_TwoPoleFilter       | playdate.sound.twopolefilter        |\n| \\_Vector2D            | playdate.geometry.vector2D          |\n| \\_Video               | playdate.graphics.video             |\n| \\_DateTime            |                                     |\n| \\_InputHandler        |                                     |\n| \\_Metadata            |                                     |\n| \\_ModTime             |                                     |\n| \\_NewClass            |                                     |\n| \\_PowerStatus         |                                     |\n| \\_SoundControlEvent   |                                     |\n| \\_SoundSource         |                                     |\n| \\_SoundTrackNote      |                                     |\n| \\_SoundTrackNoteIn    |                                     |\n| \\_SpriteCollisionData |                                     |\n| \\_SpriteCollisionInfo |                                     |\n| \\_SystemInfo          |                                     |\n\n## Version tags\n\nSee: [@notpeter/playdate-luacats/tags](https://github.com/notpeter/playdate-luacats/tags)\n\nOur version tags correspond to [PlaydateSDK versions](https://sdk.play.date/changelog/)\nwith a numbered suffix (e.g. `luacats1`). For example: `v2.1.0-luacats2` is the second\nrevision of annotations for SDK v2.1.0.\n\nThere are valid [Semantic Versioning](https://semver.org/).\nThe suffix use makes them technically [pre-release](https://semver.org/#spec-item-9)\nversions but as long as we always have a suffix it'll be fine.\n\n## About\n\nThis was created by Peter Tripp, but much of the credit goes to\n[@sumneko](https://github.com/sumneko) and\n[@actboy168](https://github.com/actboy168) for their work on\n[lua-language-server](https://github.com/luals/lua-language-server/),\n[vscode-lua](https://github.com/luals/vscode-lua),\n[lua-debug](https://github.com/actboy168/lua-debug) and related dependencies.\n\nYou can also follow me on socials:\n\n- [@notpeter on Twitter](https://twitter.com/notpeter/)\n- [@notpeter@hachyderm.io on Mastadon](https://hachyderm.io/@notpeter)\n- [@notnotpeter on Twitch](https://twitch.tv/notnotpeter)\n- [@notnotpeter on Discord](https://discord.com/users/notnotpeter)\n- [@notpeter on Itch](https://itch.io/profile/notpeter)\n\n## Meta notes\n\n- As of 2023-08-05 None of the other [LuaCATS Definitions](https://github.com/LuaCATS)\n  have any tags at all, so we're ahead of the curve.\n  Over engineering is definitely on-brand for this project.\n- As of 2023-08-05 [Google q=luacats1](https://www.google.com/search?q=luacats1)\n  yields zero results.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnotpeter%2Fplaydate-luacats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnotpeter%2Fplaydate-luacats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnotpeter%2Fplaydate-luacats/lists"}