{"id":13633051,"url":"https://github.com/samdze/playdate-nim","last_synced_at":"2025-04-09T16:24:18.177Z","repository":{"id":65254343,"uuid":"585570077","full_name":"samdze/playdate-nim","owner":"samdze","description":"Nim bindings with extra features for the Playdate SDK","archived":false,"fork":false,"pushed_at":"2024-10-23T21:19:39.000Z","size":17130,"stargazers_count":65,"open_issues_count":9,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-24T09:37:36.600Z","etag":null,"topics":["game-development","nim","nim-lang","playdate","playdate-sdk"],"latest_commit_sha":null,"homepage":"","language":"Nim","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samdze.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-01-05T14:06:10.000Z","updated_at":"2024-10-20T21:51:44.000Z","dependencies_parsed_at":"2023-02-10T16:15:16.734Z","dependency_job_id":"dd7a1db3-c4d0-45e2-9c0e-e365ad6cdb97","html_url":"https://github.com/samdze/playdate-nim","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/samdze%2Fplaydate-nim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samdze%2Fplaydate-nim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samdze%2Fplaydate-nim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samdze%2Fplaydate-nim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samdze","download_url":"https://codeload.github.com/samdze/playdate-nim/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248066079,"owners_count":21042033,"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","nim","nim-lang","playdate","playdate-sdk"],"created_at":"2024-08-01T23:00:25.953Z","updated_at":"2025-04-09T16:24:18.145Z","avatar_url":"https://github.com/samdze.png","language":"Nim","funding_links":[],"categories":["Game Development"],"sub_categories":["Programming Frameworks \u0026 Languages"],"readme":"# Nim Playdate ![build workflow](https://github.com/samdze/playdate-nim/actions/workflows/build.yml/badge.svg)\n![Playdate Simulator 2023-01-06 at 19 41 01](https://user-images.githubusercontent.com/19392104/211077589-09d1c9ee-02a4-4804-8c2b-6a8ad1850ec3.png)\n\n## About\nPlaydate Nim bindings, aiming to provide:\n- C comparable performance\n- Concise and easy syntax\n- More ergonomic API over the C API\n- Automatic memory management\n\nThe main takeaway is that, while this is to some extent a 1 to 1 mapping of the C API, it also adds extra features such as reference counted memory, OOP syntax, many other nice to haves and enhanced developer experience.\n\nThe bindings are perfectly usable but a few breaking changes are expected on the road to v1.0.\n\u003chr\u003e\n\nHere's a quick comparison between the main languages usable on the Playdate:\nLanguage | C | Lua | Nim  |\n:---- | ---- | ---- | ----\n**Performance** | ✔ Great | Decent | ✔ Great\n**Memory Management** | ✖ No management | ✔ Garbage collected | ✔ Reference counted\n**Memory usage** | ✔ Lowest | Acceptable | ✔ Low\n**Typing** | Static | Dynamic | Static\n**API** | Low level | High level | Mixed\n**Syntax** | Quite easy | ✔ Easiest \u0026 concise | ✔ Easy \u0026 concise\n**Error checking** | Basic compile + runtime | ✖ Mostly runtime | ✔ Compile time + runtime\n**OOP** | ✖ Not supported | ✔ Supported | ✔ Supported\n\nThis package is an independent bindings library, not affiliated with Panic.\n\n## Getting Started\n\n### Prerequisites\n\n- Playdate SDK\n- Nim 2+ ([recommended extension for VSCode](https://marketplace.visualstudio.com/items?itemName=NimLang.nimlang))\n- Nimble 0.14.2+ (check with `nimble -v`)\n- `PLAYDATE_SDK_PATH` environment variable\n- [SDK Prerequisites](https://sdk.play.date/Inside%20Playdate%20with%20C.html#_prerequisites) based on OS, and [MinGW on Windows](https://code.visualstudio.com/docs/cpp/config-mingw).\n\nMake sure the `gcc-arm-none-eabi` toolchain being used is the one shipped with the Playdate SDK.\nIf you're using a package manager like Homebrew, another `gcc-arm-none-eabi` installation could shadow the SDK toolchain.\n\n### Installation\n\nYou can quickly start using the bindings opening the `playdate_example` project included in this repository.\u003cbr\u003e\nIf you want to start from scratch, here are the steps to follow:\n\n1. If you haven't done it already, start creating a folder (snake_case) and initializing your nimble package inside it running:\n\n   ```shell\n   nimble init\n   ```\n\n   Choose `binary` as the package type.\n\n2. Install the `playdate` package:\n\n   ```shell\n   nimble install playdate\n   ```\n\n3. Add the `playdate` package as a dependency in your nimble file:\n\n   ```shell\n   echo 'requires \"playdate\"' \u003e\u003e *.nimble;\n   ```\n\n## Usage\n\n`playdate_example` contains a basic example of the bindings utilization.\nThe example code is in `playdate_example/src/playdate_example.nim`.\n\nHere's also a minimal snippet to make a Nim application:\n\n```nim\nimport playdate/api\n\nvar nimLogoBitmap: LCDBitmap\n\nproc update(): int {.raises: [].} =\n    nimLogoBitmap.draw(168, 88, kBitmapUnflipped)\n\n# This is the application entrypoint and event handler\nproc handler(event: PDSystemEvent, keycode: uint) {.raises: [].} =\n    if event == kEventInit:\n        # Errors are handled through exceptions, this is an inline try/except\n        nimLogoBitmap = try: playdate.graphics.newBitmap(\"/images/nim_logo\") except: nil\n        # playdate is the global PlaydateAPI instance, available when playdate/api is imported\n        playdate.system.setUpdateCallback(update)\n\n# Used to setup the SDK entrypoint\ninitSDK()\n```\n\nCompile the project (pdx) for the simulator using the `pdn` binary that gets added when\nyou ran `nimble install playdate`:\n\n```sh\npdn simulator\n```\n\nFor the device (pdx):\n\n```sh\npdn device\n```\n\nYou can also build for simulator and launch it in one command:\n\n```sh\npdn simulate\n```\n\nNote that the `pdn` command attempts to configure your environment as needed to\ncomplete the build. This includes creating a `pdxinfo` file automatically, updating your\n`config.nims`, and adding entries to your `.gitignore`. If you don't want this behavior, you\ncan add the `--no-auto-config` flag, which will disable this.\n\n### Custom pdxinfo values\n\nRunning `pdn` will automatically generate a `pdxinfo` file based on the project\ndetails in your packages `nimble` file. If you need to customize these values, you can\nadd a `pdxinfo` file to the root of your package.\n\n## Examples\n\nThe example project `playdate_example` also contains VSCode launch configurations to build, start and debug your Nim application from the editor.\n\nEach project contains a `config.nims` file that can be edited to customize how the project should be built, e.g. adding libraries or other external code.\n\nHere's an example of a `config.nims` that links a pre-built static library called chipmunk:\n\n```nim\ninclude playdate/build/config\n\n# Add a search path for libraries based on OS.\nif defined(device):\n    switch(\"passL\", \"-L\" \u0026 getCurrentDir() / \"lib\" / \"device\")\nelif defined(windows):\n    switch(\"passL\", \"-L\" \u0026 getCurrentDir() / \"lib\" / \"windows\")\nelif defined(macosx):\n    switch(\"passL\", \"-L\" \u0026 getCurrentDir() / \"lib\" / \"macos\")\nelif defined(linux):\n    switch(\"passL\", \"-L\" \u0026 getCurrentDir() / \"lib\" / \"linux\")\nelse:\n    echo \"Platform not supported!\"\n# Link the chipmunk library.\nswitch(\"passL\", \"-lchipmunk\")\n```\n\n## Interoperability with Lua\n\nNim can be used together with Lua.\nThere are two ways you can use Nim and Lua in the same project:\n1. The main loop is defined in Nim, but you want to call a few Lua functions.\n2. The main loop is defined in Lua, but you want to call Nim functions.\n\nEither way, you can provide Lua with your Nim functions during Lua initialization:\n\n```nim\nproc nimInsideLua(state: LuaStatePtr): cint {.cdecl, raises: [].} = ...\n\n# Application entrypoint and event handler\nproc handler(event: PDSystemEvent, keycode: uint) {.raises: [].} =\n    if event == kEventInitLua: # Lua initialization event\n        # Add a function `nimInsideLua` to the Lua environment\n        playdate.lua.addFunction(nimInsideLua, \"nimInsideLua\")\n        # If you want to use Nim to define the main loop, set the update callback\n        playdate.system.setUpdateCallback(update)\n```\n\nCalling a Lua function from Nim:\n\n```nim\ntry:\n    # Push the argument first\n    playdate.lua.pushInt(5)\n    playdate.lua.callFunction(\"funcWithOneArgument\", 1)\nexcept:\n    playdate.system.logToConsole(getCurrentExceptionMsg())\n```\n\n---\nThis project is a work in progress, here's what is missing right now:\n- various playdate.sound funcionalities (but FilePlayer, SamplePlayer and SoundSequence are available)\n- playdate.json, but you can use Nim std/json, which is very convenient\n- advanced playdate.lua features, but basic Lua interop is available\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamdze%2Fplaydate-nim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamdze%2Fplaydate-nim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamdze%2Fplaydate-nim/lists"}