{"id":14963962,"url":"https://github.com/jondubois/iogrid","last_synced_at":"2025-09-11T07:35:30.248Z","repository":{"id":142145583,"uuid":"75413330","full_name":"jondubois/iogrid","owner":"jondubois","description":"Multiplayer game engine/framework built using SocketCluster and Phaser","archived":false,"fork":false,"pushed_at":"2022-08-10T07:01:38.000Z","size":10219,"stargazers_count":489,"open_issues_count":4,"forks_count":60,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-03-29T12:06:51.420Z","etag":null,"topics":["framework","game-development","game-engine","multiplayer","nodejs","phaser","scale","socketcluster","websocket"],"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/jondubois.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,"governance":null}},"created_at":"2016-12-02T16:43:06.000Z","updated_at":"2025-03-27T12:40:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"fb196d10-3785-4c34-aabc-07476ab90e9b","html_url":"https://github.com/jondubois/iogrid","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/jondubois%2Fiogrid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jondubois%2Fiogrid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jondubois%2Fiogrid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jondubois%2Fiogrid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jondubois","download_url":"https://codeload.github.com/jondubois/iogrid/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247339155,"owners_count":20923014,"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":["framework","game-development","game-engine","multiplayer","nodejs","phaser","scale","socketcluster","websocket"],"created_at":"2024-09-24T13:32:23.901Z","updated_at":"2025-04-05T13:06:00.299Z","avatar_url":"https://github.com/jondubois.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"IOGrid\n======\n\n[![Join the chat at https://gitter.im/SocketCluster/iogrid](https://badges.gitter.im/SocketCluster/iogrid.svg)](https://gitter.im/SocketCluster/iogrid?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\nIOGrid is an IO game engine/framework built using SocketCluster and Phaser.\nIt lets you build multi-player games like Agar.io and Slither.io and also multi-player simulations/experiments for research purposes.\nIt is designed to scale across multiple processes to make use of all CPU cores on a machine.\n\nThe game world is divided into cells which will be distributed across available SC worker processes.\nBasic initial tests indicate that this engine can scale linearly across available CPU cores - I've found that doubling\nthe number of worker processes allowed the engine to handle approximately double the number of bots whilst maintaining the average CPU usage\nper worker process at 50%.\n\nEach cell in the world has its own instance of a cell controller (`cell.js`) - Ideally, this is where you should put all your back end game logic.\nIf you follow some simple structural guidelines, your code should automatically scale.\nWith this approach, you should be able to build very large worlds which can host thousands of concurrent players.\n\nIf you've built a game using this engine, feel free to contribute back to this repo.\nAlso, feel free to get in touch with me directly by email (see my GitHub profile http://github.com/jondubois) if you'd like to chat, have feedback,\nneed advice or need help with a project.\n\n\u003cimg alt=\"IOGrid demo\" src=\"public/img/iogrid.gif\" title=\"IOGrid demo\" /\u003e\n\nSpecial thanks to the Percepts and Concepts Laboratory at Indiana University (http://cognitrn.psych.indiana.edu/) for sponsoring this project.\n\n### Developing\n\nThe front-end code is in `public/index.html`, the back-end code is in `worker.js` and `cell.js`.\nRead the comments in the code for more details about how it all works.\n\n### Running\n\nTo run on your machine, you need to have Node.js `v6.0.0` or higher installed.\nThen you can either clone this repo with Git using the command:\n\n```\ngit clone git@github.com:SocketCluster/iogrid.git\n```\n\n... Or you can download the zip: https://github.com/SocketCluster/iogrid/archive/master.zip and extract it to a directory of your choice.\n\nOnce you have this repo setup in a `iogrid` directory on your machine, you need to navigate to it using the terminal and then run:\n\n```\nnpm install\n```\n\nThen (while still inside the `iogrid` directory) you can launch the SocketCluster server using:\n\n```\nnode server\n```\n\nTo run the demo, navigate to `http://localhost:8000` in a browser - You should see a rabbit which you can move around using the arrow keys.\n\nTo test the multi-player functionality from your localhost:\n\nOpen up another browser window/tab to `http://localhost:8000` and put it side-by-side with the first window/tab - You should now have two rabbits - Each one can be controlled from a different tab.\n\nNote that while this demo demonstrates a few important optimizations, it can still be optimized further.\nFor production usage, among other things, you may want to improve the current codec to make the packets that are sent to the client even smaller.\nYou may want to build your own codec on top of https://github.com/SocketCluster/sc-codec-min-bin.\n\nIf you want to run the server on port 80, you'll need to run the SocketCluster server with `sudo node server -p 80`.\n\nFor more info about SocketCluster, visit http://socketcluster.io/.\n\nIf you want to find out more about authentication and authorization, you may want to look into SC middleware: http://socketcluster.io/#!/docs/middleware-and-\n\nTo run the engine on multiple CPU cores, you just need to add more worker and broker processes.\nYou can do this by adding extra parameters to the node server command (`-w` is the number of worker processes and `-b` is the number of broker processes):\n\n```\nnode server -w 3 -b 1\n```\n\nUnless your CPU/OS is particularly efficient with multitasking, you generally want to have one process per CPU core (to avoid sharing cores/context switching penalties). Note that in the example above, we are launching 4 processes in total; 3 workers and 1 broker.\n\nDeciding on the correct ratio of workers to brokers is a bit of a balancing act and will vary based on your specific workload - You will have to try it out and watch your processes. When you launch the engine, SocketCluster will tell you the PIDs of your worker and broker processes.\n\nBased on the rudimentary tests that I've carried out so far, I've found that you generally need more workers than brokers. The ratio of workers to brokers that seems\nto work best for most use cases is approximately 2:1.\n\nAlso note that cell controllers (`cell.js`) will be evenly sharded across available workers. For this reason, it is highly recommended that you divide your world grid\nin such a way that your number of worker processes and total number of cells share a common factor. So for example, if you have 3 workers, you can have a world grid with dimensions of 3000 * 3000 pixels made up of 3 cells of dimensions 1000 * 3000 (rectangular cells are fine; in fact, I highly encourage them since they are more efficient).\n\n### More Info\n\nIt's still very early for this project, here are some things that still need improving:\n\n- The front end needs some sort of motion smoothing since we don't want to set the WORLD_UPDATE_INTERVAL too high (for bandwidth reasons) and so the animation should be smoothed out on the front end.\n- The front end needs an overall cleanup; maybe we need to move the core logic outside of index.html into its own .js file... And maybe we can start using the import statement (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) to load dependencies?\n- We need to make a custom SocketCluster codec specifically for this game engine to compress all outgoing messages to be as small as possible. Right now it's just using a general-purpose binary compression codec for SC - We should add another codec layer on top of this.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjondubois%2Fiogrid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjondubois%2Fiogrid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjondubois%2Fiogrid/lists"}