{"id":18450512,"url":"https://github.com/joshiemoore/p8modem","last_synced_at":"2025-04-08T01:33:28.219Z","repository":{"id":56761795,"uuid":"524754138","full_name":"joshiemoore/p8modem","owner":"joshiemoore","description":"General-purpose WebSocket modem for PICO-8","archived":false,"fork":false,"pushed_at":"2022-08-14T22:36:39.000Z","size":30,"stargazers_count":13,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-23T04:11:20.473Z","etag":null,"topics":["javascript","lua","pico-8","retrocomputing","retrogaming","websocket"],"latest_commit_sha":null,"homepage":"http://p8modem.net","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joshiemoore.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-08-14T18:51:08.000Z","updated_at":"2025-01-06T03:30:22.000Z","dependencies_parsed_at":"2022-08-16T02:00:57.219Z","dependency_job_id":null,"html_url":"https://github.com/joshiemoore/p8modem","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/joshiemoore%2Fp8modem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshiemoore%2Fp8modem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshiemoore%2Fp8modem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshiemoore%2Fp8modem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joshiemoore","download_url":"https://codeload.github.com/joshiemoore/p8modem/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247760845,"owners_count":20991531,"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":["javascript","lua","pico-8","retrocomputing","retrogaming","websocket"],"created_at":"2024-11-06T07:25:25.895Z","updated_at":"2025-04-08T01:33:27.963Z","avatar_url":"https://github.com/joshiemoore.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# p8modem\np8modem is a general-purpose WebSocket \"modem\" for PICO-8. You can use it to write PICO-8\nprograms which interact with WebSocket servers, in order to make multiplayer games,\nchat programs, BBS services, or other networked software.\n\n[Click this link](http://p8modem.net/picochat/) to access picochat, a basic chat program\nimplemented using p8modem.\n\np8modem is free software licensed under the terms of the GNU GPLv3. See LICENSE.txt\nfor details.\n\n## PICO-8 Developer Guide - Use p8modem in your own programs!\nTo use p8modem in your own programs, you must deploy your program as a web application\nand include `p8modem.js` in the generated HTML. Here are a list of steps you can follow:\n\n1. Write a PICO-8 program using the p8modem API. For example, here is a simple program\n   that just sends \"Hello World!\" over the WebSocket connection:\n\n```\n-- include the p8modem API\n#include p8modem.lua\n\nfunction _init()\n  p8m_send(\"Hello World!\")\nend\n```\n\n2. Save the program as `helloworld.p8`.\n3. Copy `p8modem.lua` from this repository to the directory containing your\n   new program so that the p8modem Lua API can be included. On Linux, your\n   PICO-8 carts will be found under `~/.lexaloffle/pico-8/carts/`\n4. Copy `p8modem.js` from this repository to the same directory you copied\n   `p8modem.lua` to in the previous step.\n5. Open your copy of `p8modem.js` in a text editor. Change `SOCKET_URL` to a\n   URL that points to the WebSocket server you're communicating with.\n6. Now export your program as a web application from within PICO-8:\n   `\u003e EXPORT HELLOWORLD.HTML`\n7. Open `helloworld.html` in a text editor, scroll to the bottom, and insert\n   this line:\n   \n   `\u003cscript type=\"text/javascript\" src=\"p8modem.js\"\u003e\u003c/script\u003e`\n   \n   right below the comment that says `\u003c!-- Add content below the cart here --\u003e`.\n8. Finally, open `helloworld.html` in a web browser, and when you run the cart,\n   your PICO-8 program will send the message `Hello World!` to the WebSocket\n   server.\n\n   If the message `p8modem has lost connection` appears, this means that you have\n   entered the wrong URL for `SOCKET_URL` in `p8modem.js`, or the WebSocket server\n   is not running.\n\nIf you would like to move your final application elsewhere, for example to deploy\nit to a web server, just make sure that you keep `helloworld.html`, `helloworld.js`,\nand `p8modem.js` all in the same directory. Replace `helloworld` with whatever you\nnamed your program. You do not need to copy `p8modem.lua` to your web server.\n\nImplementing your server-side WebSocket code is left as an exercise for the\nreader, but you can find examples in the `examples/` directory. When you are sending\na packet from your WebSocket server to PICO-8/p8modem, remember that the first byte of\nthe packet must be the total length of the packet, and that packets are limited to\n128 total bytes in size (including the length byte).\n\nPlease see the `Limitations` section for items to note while using p8modem\nto develop networked PICO-8 programs. Feel free to open an issue if you\nhave problems integrating p8modem into your own code.\n\n### API Reference\n\nThese functions are available via `p8modem.lua` for developers to interact with p8modem\nin order to communicate with a WebSocket server.\n\n* `p8m_send(buf)` - Send a packet to the server. `buf` can either be a string\n  or an array of bytes. Packet data is limited to 127 bytes in size.\n\n* `p8m_recv()` - If there is a received packet available to be read, this\n  function returns an array of bytes containing the packet data. The returned\n  byte array will contain at maximum 127 bytes. If there is no incoming\n  packet available to be read, this function returns `nil`.\n\n  Received packets are stored in a queue by p8modem, so they will be available\n  to be read as the GPIO buffer is available.\n\n## Limitations\n* p8modem only works when your PICO-8 program is deployed as a web application,\n  and will not work when deployed via other methods. This is because p8modem\n  uses JavaScript to access the PICO-8's GPIO memory and relay data over the\n  WebSocket connection.\n* Packet data sent with `p8m_send()` is limited to 127 bytes in size.\n* Operations for sending and receiving packets both share the same buffer\n  in GPIO memory. Sending takes priority over receiving, so if you call\n  `p8m_send()` without first calling `p8m_recv()` to see if there is a packet\n  available to be read, the received packet will be lost.\n* p8modem will not work in cases where very-rapid communication is needed.\n  Sending more than one packet per frame will currently not work in most cases,\n  though future versions of p8modem may address this issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshiemoore%2Fp8modem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoshiemoore%2Fp8modem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshiemoore%2Fp8modem/lists"}