{"id":13630081,"url":"https://github.com/sean-codes/cs-engine","last_synced_at":"2025-08-20T07:30:53.465Z","repository":{"id":91334714,"uuid":"69186435","full_name":"sean-codes/cs-engine","owner":"sean-codes","description":"2D Javascript Game Engine","archived":false,"fork":false,"pushed_at":"2024-07-01T05:36:22.000Z","size":14700,"stargazers_count":54,"open_issues_count":0,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-27T14:04:30.745Z","etag":null,"topics":["2d-game","2d-game-engine","engine","game","game-development","game-engine","gamedev"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/sean-codes.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":"2016-09-25T19:40:37.000Z","updated_at":"2024-09-15T01:15:35.000Z","dependencies_parsed_at":"2024-11-08T21:41:23.608Z","dependency_job_id":null,"html_url":"https://github.com/sean-codes/cs-engine","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/sean-codes%2Fcs-engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sean-codes%2Fcs-engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sean-codes%2Fcs-engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sean-codes%2Fcs-engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sean-codes","download_url":"https://codeload.github.com/sean-codes/cs-engine/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230400616,"owners_count":18219831,"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":["2d-game","2d-game-engine","engine","game","game-development","game-engine","gamedev"],"created_at":"2024-08-01T22:01:29.442Z","updated_at":"2024-12-19T08:09:17.705Z","avatar_url":"https://github.com/sean-codes.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# CS-Engine\nengine for building 2D games\n\n\u003e a love story\n\n![example image](./example.gif)\n\n## Examples\n\n- [bird](http://sean-codes.github.io/cs-engine/example/bird/index.html)\n   - flappy bird clone\n   - sound demo\n- [cube](http://sean-codes.github.io/cs-engine/example/cube/index.html)\n   - surfaces for fake lighting\n   - GUI surface for interface\n   - touch reachable within the game surface\n      - drag the crate\n   - networking\n- [multitouch](http://sean-codes.github.io/cs-engine/example/multitouch/index.html)\n   - multiple touch points\n   - mouse and touch events can be combined\n- [matterjs](https://sean-codes.github.io/cs-engine/example/matterjs/index.html)\n   - integrating a 3rd party physics engine\n\n## Boilerplate\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n  \u003chead\u003e\n    \u003c!-- 1. include cs-engine --\u003e\n    \u003cscript id=\"cs-engine\" src='../../main.web.js'\u003e\u003c/script\u003e\n  \u003c/head\u003e\n  \u003cbody style=\"-ms-touch-action: none; touch-action: none\"\u003e\n    \u003c!-- 2. add a canvas --\u003e\n    \u003ccanvas\u003e\u003c/canvas\u003e\n\n    \u003c!-- 3. run cs.load with config --\u003e\n    \u003cscript\u003e\n\n      cs.load({\n        path: '../../', // path to parts\n        canvas: document.querySelector('canvas'),\n        objects: {\n          aRectangle: {\n            draw: ({ object, cs }) =\u003e {\n              cs.draw.fillRect({ x: 0, y: 0, width: 50, height: 50 })\n            }\n          }\n        },\n        start: ({ object, cs }) =\u003e {\n          cs.object.create({ type: 'aRectangle' })\n        }\n      })\n\n    \u003c/script\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n## Initialization\ncs.load loads assets and initializes a canvas\n\n```js\n/**\n * load function\n * @arg {object} options - the options\n * @arg {string} options.parts - path to cs-engine parts\n * @arg {string} options.canvas - the id of the canvas to use\n * @arg {array of objects} options.sprites - the list of sprites to load\n * @arg {array of objects} options.scripts - the list of sprites to load\n * @arg {array of objects} options.sounds - the list of sounds to load\n * @arg {array of objects} options.storages - the list of storages to load\n * @arg {array of objects} options.objects - initial game objects\n * @arg {function} options.start - called when finished loading\n **/\n```\n\n## Sprite Loading Options\nWhen loading sprites we can specify some options. Only path is required\n\n```js\n/**\n * sprite load\n * @arg {object} options - the options\n * @arg {string} options.path - the relative path to the .png file\n * @arg {string} [options.name=calculated] - override the filename and set sprite name]\n * @arg {number} [options.frames=0] - how many frames in the sprite sheet\n * @arg {number} [options.width=calculated] - The width of a frame\n * @arg {number} [options.height=calculated] - The height of a frame\n * @arg {number} [options.xoff=0] - The horizontal offset when drawing\n * @arg {number} [options.yoff=0] - The vertical offset when drawing\n * @arg {object} [options.mask=calculated] - And object with { width, height }\n **/\n\ncs.load({\n   ...\n   sprites: [\n      { path: 'sprites/spr_player' },\n   ]\n})\n```\n\n## Script Loading Options\nAny `.js` files that are required for the project\n```js\n/**\n * script load\n * @arg {object} options - the options\n * @arg {string} options.path - the the relative path to the .js file\n **/\n\ncs.load({\n   ...\n   scripts: [\n      { path: './objects/obj_player.js' }\n   ]\n})\n```\n\n## Room\nIn the start function define the room size.\n\n\u003e note: this can be changed at any time\n\n```js\n/**\n * room setup\n * @arg {object} options - the options\n * @arg {number} [options.width] - The width of a room\n * @arg {number} [options.height] - The height of a room\n * @arg {string} [options.background] - The background of the room\n **/\n\n// example room 192px by 192px and a grey background\ncs.room.setup({ width: 192, height: 192, background: \"#222\" })\n```\n\n\n## Camera\nThe camera defines the area of a non GUI canvas (the game canvas) that should be displayed at anytime.\n\nExperiment with maxWidth and maxHeight and the engine will setup the best scale\nto work with those values.\n\nIn the start function define the camera settings.\n\n\u003e note: this can be changed at any time\n\n```js\n/**\n * camera setup\n * @arg {object} options - the options\n * @arg {number} [options.maxWidth] - The max width of the camera\n * @arg {number} [options.maxHeight] - The max height of the camera\n * @arg {number} [options.smoothing=1] - Amount of smoothing when updating follow position\n **/\n\n// example camera maxWidth and Height\ncs.camera.setup({ maxWidth:300, maxHeight:200 })\n```\n\n## Game Objects\nGame objects have a create, step, and draw function. The are stored in `cs.objects` array. Add them in the init or as external script files.\n\n\u003e in the init\n\n```js\ncs.load({\n  ...\n  objects: {\n    myObjName: {\n      create: ({ object, cs, attr }) =\u003e { console.log('i run when created') },\n      step: ({ object, cs }) =\u003e { console.log('i run each frame of the game') },\n      draw: ({ object, cs }) =\u003e { console.log('i run after the step for drawing') }\n\t }\n  }\n  ...\n})\n```\n\n\u003e External script file\n\n```js\n// FILE: objects/obj_name.js\ncs.objects.myObjName = {\n  create: ({ object, cs, attr }) =\u003e { console.log('i run when created') },\n  step: ({ object, cs }) =\u003e { console.log('i run each frame of the game') },\n  draw: ({ object, cs }) =\u003e { console.log('i run after the step for drawing') }\n}\n\n// Add as script path to assets\ncs.load({\n   ...\n   assets: {\n      scripts: [\n         { path: 'objects/obj_name.js' }\n      ]\n   }\n   ...\n})\n```\n\nCreate an object using `cs.object.create()`\n```js\ncs.object.create({\n   type: 'obj_name',\n   attr: {\n      // Attributes to add to the game object example x/y\n      x: 50,\n      y: 50\n   }\n})\n```\n\n## Drawing\n\n#### Sprites\n```js\n/**\n * @arg {object} options - the options\n * @arg {string} options.spr - The name of the sprite\n * @arg {number} [options.y] - the y position\n * @arg {number} [options.y] - the y position\n * @arg {number} [options.width=width] - The width to draw the sprite\n * @arg {number} [options.height=height] - The height to draw the sprite\n * @arg {number} [options.scaleX=1] - Horizontal scaling\n * @arg {number} [options.scaleY=1] - Vertical scaling\n * @arg {number} [options.angle=0] - (0 - 360) draw sprite rotated in degrees\n **/\n\n// example drawing player sprite at coordinates (50, 50)\ncs.draw.sprite({ spr: 'spr_player', x: 50, y: 50 })\n```\n\n#### Text\n```js\n/**\n * @arg {object} options - the options\n * @arg {string} options.text - The text to draw\n * @arg {number} [options.x] - The x position\n * @arg {number} [options.y] - the y position\n **/\n\n// example drawing text 'hello world' at coordinated (50, 50)\ncs.draw.text({ text: 'hello world', x: 50, y: 50 })\n```\n\n#### Shapes\n\n###### Fill Recangle\n```js\n/**\n * @arg {object} options - the options\n * @arg {number} [options.x] - The x position\n * @arg {number} [options.y] - the y position\n * @arg {number} [options.width] - the width\n * @arg {number} [options.height] - the height\n **/\n\n// example fill rectangle in top corner with width 50 and height 50\ncs.draw.fillRect({ x: 0, y: 0, width: 50, height: 50 })\n```\n\n###### Stroke Rectangle\n```js\n/**\n * @arg {object} options - the options\n * @arg {number} [options.x] - The x position\n * @arg {number} [options.y] - the y position\n * @arg {number} [options.width] - the width\n * @arg {number} [options.height] - the height\n **/\n\n// example outlined rectangle in top corner with width 50 and height 50\ncs.draw.strokeRect({ x: 0, y: 0, width: 50, height: 50 })\n```\n\n###### Line\n```js\n/**\n * @arg {object} options - the options\n * @arg {number} [options.x1] - The start x position\n * @arg {number} [options.y1] - the start y position\n * @arg {number} [options.x2] - the end x position\n * @arg {number} [options.y2] - the end y position\n **/\n\n// example of a line starting in top left corner to (50, 50)\ncs.draw.line({ points: [ { x:0, y:0 }, { x:50, y:50 } ] })\n```\n\n#### Settings\n\u003e Note: Draw settings are reset after any drawing event!\n\n```js\n/**\n * @arg {object} options - the options\n * @arg {number} [options.color='#000'] - HEX/RGB/String value of color\n * @arg {number} [options.font='12px Arial'] - Font setting. Font Size space Font Name\n * @arg {number} [options.width=1] - line width for stroke functions\n * @arg {number} [options.alpha=1] - 0 being invisible 1 being fully visible\n * @arg {number} [options.textAlign='start'] - start/middle/end horizontal align\n * @arg {number} [options.textBaseline='top'] - top/bottom/middle/baseline vertical align\n * @arg {number} [options.lineHeight=10] - line height spacing for text\n * @arg {number} [options.operation='source-over'] - set canvas manual on draw operations\n **/\n\n// example setting draw color to red and font to 16px arial\ncs.draw.settings({ color: 'red', font: '16px Arial' })\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsean-codes%2Fcs-engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsean-codes%2Fcs-engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsean-codes%2Fcs-engine/lists"}