{"id":15394349,"url":"https://github.com/xyproto/pixelprotocol","last_synced_at":"2026-01-24T15:33:36.994Z","repository":{"id":65734377,"uuid":"149093257","full_name":"xyproto/pixelprotocol","owner":"xyproto","description":"Experimental protocol for streaming games","archived":false,"fork":false,"pushed_at":"2025-09-18T21:53:29.000Z","size":27,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-18T23:56:33.045Z","etag":null,"topics":["binary","convolution-filters","for-fun","gamedev","games","midi","pixels","protocol","sprite","streaming"],"latest_commit_sha":null,"homepage":"","language":null,"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/xyproto.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}},"created_at":"2018-09-17T08:28:47.000Z","updated_at":"2025-09-18T21:53:32.000Z","dependencies_parsed_at":"2023-02-07T07:39:02.371Z","dependency_job_id":null,"html_url":"https://github.com/xyproto/pixelprotocol","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/xyproto/pixelprotocol","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xyproto%2Fpixelprotocol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xyproto%2Fpixelprotocol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xyproto%2Fpixelprotocol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xyproto%2Fpixelprotocol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xyproto","download_url":"https://codeload.github.com/xyproto/pixelprotocol/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xyproto%2Fpixelprotocol/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28730320,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T10:24:43.181Z","status":"ssl_error","status_checked_at":"2026-01-24T10:24:36.112Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["binary","convolution-filters","for-fun","gamedev","games","midi","pixels","protocol","sprite","streaming"],"created_at":"2024-10-01T15:23:22.337Z","updated_at":"2026-01-24T15:33:36.988Z","avatar_url":"https://github.com/xyproto.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# pixelprotocol\n\nPixelProtocol (pipro) is a protocol for defining what is being sent between the GUI client and the game engine.\n\nIt's for implementing games where old-school looking pixel art can be appreciated.\n\n## Features and limitations\n\n* 256 indexed colors.\n* A size of 320x200 pixels is recommended.\n* Should be possible to implement both in 16-bit assembly for DOS and in a browser.\n* 4-channel audio with multiple waveforms and ADSR envelopes.\n* Text rendering with 8 font slots and scaling.\n* Advanced sprite operations including rotation, scaling, and collision detection.\n* Timing control and frame synchronization.\n* Memory management for palettes and screen buffers.\n\n## Q\u0026A\n\n* Q: Wouldn't it be cooler if Vulkan commands was sent instead? Or OpenGL? Or SDL2?\n* A: Protocols for OpenGL over network already exists and I want to keep things really simple.\n\n* Q: Can't you just use VNC?\n* A: No, I want something specifically for games or demoscene demos that use 320x200 pixels, 256 colors.\n\n# Protocol Definition\n\n* Version: 0.2\n\n## Protocol Header\n\n| name | type | description |\n|------------|-------------------|-------------------------------------------------|\n| ver | uint16 | protocol version |\n| width | uint16 | width |\n| height | uint16 | height |\n| commands | []uint16 | list of commands (uint8 cmd + uint8 argument) |\n\nThe commands can be streamed.\n\n## Commands\n\n### Color palette\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x00 | choose palette color | prepare for filling the palette |\n| 0x01 | set red value of chosen palette color | set the color |\n| 0x02 | set green value of chosen palette color | set the color |\n| 0x03 | set blue value of chosen palette color | set the color |\n\n### Drawing pixels\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x04 | choose pixel color | prepare for drawing |\n| 0x05 | set x position | |\n| 0x06 | set y position | |\n| 0x07 | add to x position | |\n| 0x08 | add to y position | |\n| 0x09 | plot | draw a pixel |\n\n##### Q\u0026A\n\n* Q: What is the \"add to x position\" command for?\n* A: since all arguments are bytes, it's needed to be able to specify X coordinates from 256..320.\n\n* Q: Isn't that a bit impractical?\n* A: Perhaps, but it makes the protocol very simple and uniform. All commands takes a byte as an argument.\n\n\n### Filling\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x0a | clear | clear everything with the selected color |\n\n---\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x0b | draw linewise until nonblack or end | for filling the pixel buffer |\n| 0x0c | draw backwards linewise until nonblack or end | for filling the pixel buffer |\n\n### Flipping\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x0d | flip | update all pixels |\n| 0x0e | sprite flip | update pixels where sprites have been |\n\n### Drawing lines\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x0f | choose color for start of line | prepare to draw a line |\n| 0x10 | choose color for end of line | prepare to draw a line |\n\n---\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x11 | set x coordinate for start of line | prepare to draw a line |\n| 0x12 | set y coordinate for start of line | prepare to draw a line |\n| 0x13 | set x coordinate for end of line | prepare to draw a line |\n| 0x14 | set y coordinate for end of line | prepare to draw a line |\n\n---\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x15 | add to x coordinate for start of line | prepare to draw a line |\n| 0x16 | add to y coordinate for start of line | prepare to draw a line |\n| 0x17 | add to x coordinate for end of line | prepare to draw a line |\n| 0x18 | add to y coordinate for end of line | prepare to draw a line |\n\n---\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x19 | draw a line | draw the line |\n\n\n### Drawing triangles\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x1a | choose color for p0 | prepare to draw a filled triangle |\n| 0x1b | choose color for p1 | prepare to draw a filled triangle |\n| 0x1c | choose color for p2 | prepare to draw a filled triangle |\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x1d | set x coordinate for p0 | prepare to draw a filled triangle |\n| 0x1e | set y coordinate for p0 | prepare to draw a filled triangle |\n| 0x1f | set x coordinate for p1 | prepare to draw a filled triangle |\n| 0x20 | set y coordinate for p1 | prepare to draw a filled triangle |\n| 0x21 | set x coordinate for p2 | prepare to draw a filled triangle |\n| 0x22 | set y coordinate for p2 | prepare to draw a filled triangle |\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x23 | add to x coordinate for p0 | prepare to draw a filled triangle |\n| 0x24 | add to y coordinate for p0 | prepare to draw a filled triangle |\n| 0x25 | add to x coordinate for p1 | prepare to draw a filled triangle |\n| 0x26 | add to y coordinate for p1 | prepare to draw a filled triangle |\n| 0x27 | add to x coordinate for p2 | prepare to draw a filled triangle |\n| 0x28 | add to y coordinate for p2 | prepare to draw a filled triangle |\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x29 | draw a filled or empty triangle | 0 for empty, 1 for filled |\n\n### Randomization\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x2a | choose a random color for the pixel | |\n| 0x2b | choose random colors for the line | |\n| 0x2c | choose random colors for the triangle | |\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x2d | choose random coordinates for the pixel | |\n| 0x2e | choose random coordinates for the line | |\n| 0x2f | choose random coordinates for the triangle | |\n\n### Sprites\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x30 | choose sprite ID | select a sprite to work with |\n| 0x31 | set sprite width | set sprite width |\n| 0x32 | set sprite height | set sprite height |\n| 0x33 | clear sprite | clear contents |\n| 0x34 | push pixel | adds N pixels of the selected color |\n| 0x35 | push empty | add N transparent pixels |\n| 0x36 | set x coordinate for drawing the sprite | |\n| 0x37 | set y coordinate for drawing the sprite | |\n| 0x38 | add to x coordinate for drawing the sprite | |\n| 0x39 | add to y coordinate for drawing the sprite | |\n| 0x3a | draw sprite | draw the current sprite, 2 for dbl. size |\n\n### Convolution Filters\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x40 | set convolution filter 0 | blur is 0,1,0,1,1,1,0,1,0 div 5 |\n| 0x41 | set convolution filter 1 | flame is 0,1,0,1,1,1,0,0,0 div 4 |\n| 0x42 | set convolution filter 2 | |\n| 0x43 | set convolution filter 3 | the uint8 is treated as a range from |\n| 0x44 | set convolution filter 4 | 0.0 to 1.0 |\n| 0x45 | set convolution filter 5 | |\n| 0x46 | set convolution filter 6 | |\n| 0x47 | set convolution filter 7 | |\n| 0x48 | set convolution filter 8 | |\n| 0x49 | set convolution division | |\n| 0x4a | use convolution filter | |\n\n## Keyboard, Joystick and Mouse\n\nFor returning the state of the client:\n\nCommands that return an uint16:\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|-----------------------------------------------------------------------|\n| 0x60 | is Esc | is Escape being pressed? |\n| 0x61 | is up | is W, up or joystick up pressed? args: 0 for both, 1 for P1, 2 for P2 |\n| | | Player1 has WASD and Joy1, Player2 has arrows and Joy2 |\n| 0x62 | is left | is A, left or joystick left pressed? |\n| 0x63 | is down | is S, down or joystick down pressed? |\n| 0x64 | is right | is D, right or joystick right pressed? |\n| 0x65 | is A | is Return, Comma (,) or joystick A pressed? |\n| 0x66 | is B | is Space, Dot (.) or joystick B pressed? |\n\n---\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|-----------------------------------------------------------------------|\n| 0x67 | is shift held down | uint8 argument: 0 for left, 1 for right, 2 for any, returns 1 for held down |\n| 0x68 | is alt held down | |\n| 0x69 | is ctrl held down | |\n| 0x6a | is super held down | |\n\n---\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|-----------------------------------------------------------------------|\n| 0x6b | get keybuffer | returns: 0 if empty, keycode of first in keybuffer if not empty |\n\n---\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|-----------------------------------------------------------------------|\n| 0x6c | get mouse x coordinate | |\n| 0x6d | get mouse y coordinate | |\n| 0x6e | get mouse buttons | returns: 0 for none, 1 for left, 2 for right and 3 for middle |\n\n---\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|-----------------------------------------------------------------------|\n| 0x6f | joy button | uint8 argument: button ID, returns: 1 for pressed |\n\nA channel must be set up for receiving the uint16 values that are returned by these functions.\n\n### Audio\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x70 | set audio channel | select channel 0-3 for audio operations |\n| 0x71 | set frequency | set frequency (0-255, maps to Hz range) |\n| 0x72 | set frequency high byte | extend frequency range |\n| 0x73 | set volume | set volume (0-255) |\n| 0x74 | set waveform | 0=square, 1=triangle, 2=sawtooth, 3=noise |\n| 0x75 | play tone | play tone for N frames |\n| 0x76 | stop channel | stop audio on selected channel |\n| 0x77 | set envelope attack | attack time (0-255) |\n| 0x78 | set envelope decay | decay time (0-255) |\n| 0x79 | set envelope sustain | sustain level (0-255) |\n| 0x7a | set envelope release | release time (0-255) |\n| 0x7b | play sample | play predefined sample ID |\n\n### Text Rendering\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x80 | set font | select font 0-7 |\n| 0x81 | set text color | color for text foreground |\n| 0x82 | set text background color | color for text background (255=transparent) |\n| 0x83 | set text x position | x position for text |\n| 0x84 | set text y position | y position for text |\n| 0x85 | add to text x position | for positions \u003e 255 |\n| 0x86 | add to text y position | for positions \u003e 255 |\n| 0x87 | print character | print ASCII character |\n| 0x88 | print string | print null-terminated string (follows in stream) |\n| 0x89 | set text scale | scale factor 1-8 |\n\n### Geometric Primitives\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0x90 | set circle center x | x coordinate for circle center |\n| 0x91 | set circle center y | y coordinate for circle center |\n| 0x92 | add to circle center x | for coordinates \u003e 255 |\n| 0x93 | add to circle center y | for coordinates \u003e 255 |\n| 0x94 | set circle radius | radius in pixels |\n| 0x95 | draw circle | 0=outline, 1=filled |\n| 0x96 | set rectangle x | top-left x coordinate |\n| 0x97 | set rectangle y | top-left y coordinate |\n| 0x98 | add to rectangle x | for coordinates \u003e 255 |\n| 0x99 | add to rectangle y | for coordinates \u003e 255 |\n| 0x9a | set rectangle width | width in pixels |\n| 0x9b | set rectangle height | height in pixels |\n| 0x9c | draw rectangle | 0=outline, 1=filled |\n\n### Timing and Synchronization\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0xa0 | wait frames | wait N frames (60fps assumed) |\n| 0xa1 | set frame rate | set target FPS (0=unlimited) |\n| 0xa2 | get frame counter | returns current frame number (uint16) |\n| 0xa3 | reset frame counter | reset frame counter to 0 |\n| 0xa4 | sync to vblank | wait for vertical blank |\n\n### Advanced Sprite Operations\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0xb0 | set sprite rotation | rotation angle (0-255 = 0-360°) |\n| 0xb1 | set sprite scale x | horizontal scale (128=1.0x) |\n| 0xb2 | set sprite scale y | vertical scale (128=1.0x) |\n| 0xb3 | set sprite flip | 0=none, 1=horizontal, 2=vertical, 3=both |\n| 0xb4 | check sprite collision | check if two sprites collide (returns uint16) |\n| 0xb5 | set sprite layer | drawing layer/depth (0-255) |\n| 0xb6 | set sprite alpha | transparency (0=transparent, 255=opaque) |\n\n### Memory and Data\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0xc0 | save palette | save current palette to slot N |\n| 0xc1 | load palette | load palette from slot N |\n| 0xc2 | save screen | save current screen to buffer N |\n| 0xc3 | load screen | load screen from buffer N |\n| 0xc4 | copy region | copy rectangular region (params follow) |\n\n### Program Control\n\n| cmd | uint8 argument | |\n|------|-----------------------------------------------|------------------------------------------|\n| 0xfe | toggle fullscreen | enable or disable fullscreen mode |\n| 0xff | exit | end the program |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxyproto%2Fpixelprotocol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxyproto%2Fpixelprotocol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxyproto%2Fpixelprotocol/lists"}