{"id":21578864,"url":"https://github.com/yetnt/disgamekit","last_synced_at":"2026-04-28T16:04:57.906Z","repository":{"id":177549888,"uuid":"660099639","full_name":"yetnt/disgamekit","owner":"yetnt","description":"A package that will help make discord.js bots have minigames!","archived":false,"fork":false,"pushed_at":"2023-12-09T07:55:39.000Z","size":166,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-25T01:42:30.709Z","etag":null,"topics":["2d-game","discord","discord-js","discordgame","eris-discord","game-2d","game-engine-2d","javascript","javascript-library","plane","turns","typescript","typescript-library"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/yetnt.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":"2023-06-29T08:40:42.000Z","updated_at":"2023-09-30T09:52:21.000Z","dependencies_parsed_at":"2023-07-10T20:45:43.373Z","dependency_job_id":null,"html_url":"https://github.com/yetnt/disgamekit","commit_stats":null,"previous_names":["yetity/djs-game","yetnt/disgamekit"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yetnt%2Fdisgamekit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yetnt%2Fdisgamekit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yetnt%2Fdisgamekit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yetnt%2Fdisgamekit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yetnt","download_url":"https://codeload.github.com/yetnt/disgamekit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244180446,"owners_count":20411564,"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","discord","discord-js","discordgame","eris-discord","game-2d","game-engine-2d","javascript","javascript-library","plane","turns","typescript","typescript-library"],"created_at":"2024-11-24T13:11:45.796Z","updated_at":"2026-04-28T16:04:57.839Z","avatar_url":"https://github.com/yetnt.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e disgamekit \u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n\u003cimg alt=\"Static Badge\" src=\"https://img.shields.io/badge/version-2.2.0-baige\"\u003e\n\u003c/p\u003e\n\nA small package that will help making ts/js discord bot mini games way easier!\n(placeholder for game example)\n\n## Installation\n\n```\nnpm i disgamekit\n```\n\n## Table of Contents\n\n-   [Game Class](#game-class)\n-   -   [Constructor](#constructor)\n-   -   [Methods](#methods)\n-   -   [Events](#events)\n-   -   [Example](#example-use)\n-   [Plane Class](#plane-class)\n-   -   [Constructor](#constructor-1)\n-   -   [Methods](#methods-1)\n-   [PlaneObject Class](#planeobject-class)\n-   -   [Constructor](#constructor-2)\n-   -   [Methods](#methods-2)\n-   -   [Events](#events-1)\n-   -   [Example (plane + planeobject)](#exmaple-use-plane--planeobject)\n-   [ComplexPlaneObject](#complexplaneobject-class)\n-   -   [Constructor](#constructor-3)\n-   -   [Methods](#methods-3)\n-   [All classes exmaple](#example-discordjs)\n-   [Turns Class](#turns-class)\n-   -   [Constructor](#constructor-4)\n-   -   [Methods](#methods-4)\n-   [Player Class (Turns)](#player-class)\n-   -   [Constructor](#constructor-5)\n\n## Game Class\n\nThe Game class represents a simple game controller with start, end, and error handling functionality. It manages the overall state of the game and provides methods to start, end, and handle game events.\n\n### Constructor\n\n#### Parameters\n\n-   `id` : The unique identifier for the game.\n\n```js\nconst { Game } = require('disgamekit');\nconst game = new Game('gameId');\n```\n\n### Methods\n\n#### `start`\n\nStarts the game and emit's the \"start\" event.\n\n```js\ngame.start();\n```\n\n#### `isGameOn`\n\nReturns game's current state\n\n```js\nconsole.log(game.isGameOn()); // false\ngame.start();\nconsole.log(game.isGameOn()); // true\n```\n\n#### `end`\n\nEnds the game and emit's the \"end\" event.\n\n##### Parameters\n\n-   `interaction`:**(optional)** Interaction associated with the game\n-   `custom`:**(optional)** Pass a custom string to be sent to the event listener.\n-   `plane`:**(optional)** Pass the plane to be reset.\n\n```js\ngame.start();\nconsole.log(game.isGameOn()); // true\ngame.end(interaction); // so that when the end event is emitted you can edit an embed or do something to a message.\nconsole.log(game.isGameOn()); // false\n```\n\n### Events\n\n#### \"start\"\n\nFired when the game starts\n\n```js\nconst { Game } = require('disgamekit');\n\nlet game = new Game('game');\ngame.on('start', () =\u003e {\n    console.log('Game sucessfully started!');\n});\n```\n\n#### \"end\"\n\nFired when the game ends\n\n```javascript\nconst { Game } = require('disgamekit');\n\nlet game = new Game('game');\n\ngame.on('end', () =\u003e {\n    console.log('Game ended!');\n});\ngame.end();\n\n// If you have a component to end the game, you can edit the reply one last time.\n\ngame.on('end', (i) =\u003e {\n    i.update('Game has ended.');\n});\ngame.end(interaction);\n\n// And lastly if you used a custom message\ngame.on('end', (i, c) =\u003e {\n    i.update(c);\n});\ngame.end(interaction, 'Game has ended.');\n```\n\n#### \"error\"\n\nFired when an error occurs.\n\n```js\nconst { Game } = require('disgamekit');\n\nlet game = new Game('game');\ngame.on('error', (error) =\u003e {\n    console.log('Error occured!' + error);\n});\n```\n\n### Example use\n\n```js\nconst gameId = 'game`';\nconst game = new Game(gameId);\n\ngame.on('start', () =\u003e {\n    console.log('Game started!');\n});\n\ngame.on('end', () =\u003e {\n    console.log('Game ended!');\n});\n\ngame.on('error', (error) =\u003e {\n    console.error('An error occurred with the game!:', error);\n});\n\ngame.start();\n```\n\nIn the example above, a new `Game` instance is created with a game client and a unique ID. Event listeners are added for the `start`, `end`, and `error` events. Lastly the game is started using `game.start()`.\n\n## Plane Class\n\nThe `Plane` class represents a grid-based 2d plane and provides methods to manage and manipulate objects on the plane. All objects refrenced can be found [here](#planeobject-class)\n\n### Constructor\n\n#### Parameters\n\n-   `game`: The game instance associated with the plane.\n-   `rows`: The number of rows in the plane.\n-   `columns`: The number of columns in the plane.\n-   `blank`:**(optional)** The default value for empty cells in the plane. Defaults to `null`\n\n```js\nconst { Game, Plane } = require('disgamekit');\n\nconst game = new Game('gameId');\n\nconst plane = new Plane(game, 5, 5, 'blank');\n```\n\n### Methods\n\n#### `lookupObj`\n\nLooks up an object's coordinates based on its ID.\n\n##### Parameters\n\n-   `inputValue`: The ID of the object to be looked up on the plane.\n\n```js\n// If an object with the ID: qwert was at x:2 y: 6\nplane.lookupObj('qwert'); // { x: 2, y: 6 }\n```\n\n#### `lookupCoords`\n\nLooks up the value at the specified x and y coordinates on the plane\n\n##### Parameters\n\n-   `x`:**(optional)** The x-coordinate.\n-   `y`:**(optional)** The y-coordinate\n\n```js\nplane.lookupCoords(2, 6); // \"qwert\"\n```\n\n#### `clear`\n\nClears the entire plane, removing all objects while preserving their coordinates.\n\n```js\nplane.clear();\n```\n\n#### `update`\n\nAdds/Updates/Removes Objects on the plane.\nIf provided : It will update/add to the plane\nIf not provided : It will clear the plane of any objects.\n\n##### Parameters\n\n-   `...arr`:**(optional)** Numerous objects to be updated on the plane.\n\n```js\nplane.update(object1, object2, object3, object4);\n```\n\n#### `return`\n\nReutrns a string representation of the plane, with optional row and column separators.\n\n##### Parameters\n\n-   `row`:**(optional)** The separator for rows. Defaults to an empty string.\n-   `column`:**(optional)** The separator for columns. Defaults to a line break\n\n```js\n// For example, the plane has 5 rows and 5 columns\nplane.return('', '\\n');\n/*\nblank blank blank blank blank\nblank blank blank blank blank\nblank blank blank blank blank\nblank blank blank blank blank\nblank blank blank blank blank\n*/\n```\n\n## PlaneObject Class\n\nThe PlaneObject class represents an object that can be placed on the Plane. It emits events for collision detection and can be used to create interactive game elements.\n\n### Constructor\n\n#### Parameters\n\n-   `plane`: Plane instance.\n-   `x`: The object's origin on the x-axis\n-   `y`: The object's origin on the y-axis\n-   `id`: A unique identifier for the object.\n-   `value`:**(optional)** The emoji or value to display on the plane for said object. Defaults to the object's ID.\n-   `detectCollision`:**(optional)** Whether to detect collisions with other objects. Defaults to `true`\n-   `ai`: **(optional)** Enable Auto-Movement\n\n```js\nconst { Plane, PlaneObject } = require('disgamekit');\n\nlet plane = new Plane(...)\nlet hat = new PlaneObject(plane, 0, 0, 'hat', '🧢');\n```\n\n### Methods\n\n#### `isAi`\n\nCheck if current PlaneObject is an AI\n\n```js\nconst { Plane, PlaneObject } = require('disgamekit');\n\nlet plane = new Plane(...)\nlet hat = new PlaneObject(plane, 0, 0, 'hat', '🧢', false, true);\n\nhat.isAi() // true\n```\n\n#### `start`\n\nStart tracking specified target\n\n##### Parameters\n\n-   `target`: another PlaneObject to target\n\n```js\nlet apple = new PlaneObject(plane, 5, 5, 'apple', 'a');\n\nhat.start(apple);\n```\n\n#### `step`\n\nStep 1 grid space closer to the target\n\n##### Parameters\n\n-   `target`: **(optional)** Override current target with new target\n\n```js\nhat.step(); // since it's tracking apple at (5, 5), hat will go to (1, 1)\n```\n\n#### `stop`\n\nStop running the AI\n\n```js\nhat.stop();\n\nhat.step(); // AI has not been started!\n```\n\n### Events\n\n#### \"collision\"\n\nFired when `foo` collides with a wall or another `PlaneObject` instance\n\n```js\nconst { Game, PlaneObject, Plane } = require('disgamekit');\n\nlet game = new Game('game');\nlet plane = new Plane(game, 4, 4);\nlet object = new PlaneObject(plane, 2, 0, 'object');\n\nobject.on('colllision', (i) =\u003e {\n    console.log(`Object collided with ${i.id}!`);\n});\n```\n\n## Exmaple use (Plane \u0026 PlaneObject)\n\n```js\nconst { Plane, PlaneObject } = require('disgamekit');\n\n// Create a game instance\nconst game = new Game('gameId');\n\n// Create a plane with 5 rows and 5 columns\nconst plane = new Plane(game, 5, 5);\n\n// Create plane objects\nconst object1 = new PlaneObject(plane, 2, 2, 'obj1', 'A');\nconst object2 = new PlaneObject(plane, 3, 3, 'obj2', 'B');\n\n// Update the plane with the objects\nplane.update(object1, object2);\n\n// Check for collision (This is called when collided with a wall, even if detectCollison = false.)\nobject1.on('collision', (i) =\u003e {\n    console.log(`${i} collided with object1!`);\n});\n\n// Lookup object coordinates\nconst coordinates1 = plane.lookupObj('obj1');\nconsole.log('Object 1 coordinates:', coordinates1); // Output: Object 1 coordinates: { x: 2, y: 2 }\n\n// Lookup value at coordinates\nconst value = plane.lookupCoords(3, 3);\nconsole.log('Value at coordinates (3, 3):', value); // Output: Value at coordinates (3, 3): B\n\n// Clear the plane\nplane.clear();\n\n// Update the plane with a single object\nconst object3 = new PlaneObject(plane, 1, 1, 'obj3', 'C');\nplane.update(object3);\n\n// Return the plane as a string\nconst planeString = plane.return(' ', '\\n');\nconsole.log(planeString);\n/* Output:\nnull null null null null\nnull null null null null\nnull null C null null\nnull null null null null\nnull null null null null\n*/\n```\n\nIn the example above, we create a game instance and then create a `Plane` instance with 5 rows and 5 columns. We create `PlaneObject` instances (`object1` and `object2`) with origin coordinates and values. The plane is then updated with these objects using the `update()` method.\n\nWe perform lookups on the plane using the `lookupObj()` method to retrieve the coordinates of `object1`, and the `lookupCoords()` method to retrieve the value at coordinates `(3, 3)`.\n\nThe plane is cleared using the `clear()` method and then updated with a new object (`object3`). Finally, we return the plane as a string representation using the `return()` method and print it to the console.\n\n## Example [Discord.js](https://discord.js.org/)\n\n```js\n// This works the same with interactions. But so that the code is not 6k lines long, I've used messages.\n// Discord.js and disgamekit imports\nconst {\n    Client,\n    IntentsBitField,\n    EmbedBuilder,\n    ButtonBuilder,\n    ButtonStyle,\n    ActionRowBuilder,\n} = require('discord.js');\nconst { Game, Plane, PlaneObject } = require('disgamekit');\n\nconst client = new Client({\n    intents: [\n        IntentsBitField.Flags.Guilds,\n        IntentsBitField.Flags.GuildMessages,\n        IntentsBitField.Flags.MessageContent,\n    ],\n});\n\nclient.on('ready', () =\u003e {\n    console.log(`${client.user.tag} is online`);\n});\n\n// var setup\nconst game = new Game(client, 'game');\ngame.var.score = 0;\nconst plane = new Plane(game, 10, 10, ':green_square:');\nconst moveable = new PlaneObject(\n    plane,\n    3,\n    3,\n    'moveable',\n    ':blue_square:',\n    true\n);\nconst nonmove = new PlaneObject(plane, 2, 2, 'nonmove', ':apple:');\n\n// game controls\nconst row = new ActionRowBuilder().addComponents(\n    new ButtonBuilder()\n        .setCustomId('up')\n        .setLabel('up')\n        .setStyle(ButtonStyle.Secondary),\n    new ButtonBuilder()\n        .setCustomId('down')\n        .setLabel('down')\n        .setStyle(ButtonStyle.Secondary),\n    new ButtonBuilder()\n        .setCustomId('left')\n        .setLabel('left')\n        .setStyle(ButtonStyle.Secondary),\n    new ButtonBuilder()\n        .setCustomId('right')\n        .setLabel('right')\n        .setStyle(ButtonStyle.Secondary),\n    new ButtonBuilder()\n        .setCustomId('end')\n        .setLabel('end')\n        .setStyle(ButtonStyle.Danger)\n);\n\nclient.on('messageCreate', async (m) =\u003e {\n    if (m.author.bot) return;\n    const message = m.content;\n    if (!message.includes('mjb?')) return;\n\n    let cmd = message.split('?');\n\n    switch (cmd[1]) {\n        case 'help':\n            m.reply('No.');\n            break;\n        case 'button':\n            game.start();\n            plane.update(moveable, nonmove); // show the initial state by updating the object to the grid before hand\n            await m.reply({\n                embeds: [\n                    new EmbedBuilder()\n                        .setTitle('g a m e')\n                        .setDescription(plane.return()),\n                ],\n                components: [row],\n            });\n            break;\n    }\n});\n// game events\ngame.on('start', () =\u003e {\n    console.log('Game started!');\n});\ngame.on('end', async (i) =\u003e {\n    await i.update({\n        content: `game has ended! Your final score = ${game.var.score}`,\n        components: [],\n        embeds: [],\n    }); // clear buttons so no errors occur.\n    console.log('Game ended!');\n});\nmoveable.on('collision', (obj) =\u003e {\n    // when the moveable collides with nonemoveable update the score, if wall, log it to the console.\n    if (obj.id == nonmove.id) {\n        game.var.score++;\n    } else if (obj.id == 'wall') {\n        // You can just use an if since it's 2 objects but i used an else if for documentation sake\n        console.log('Collision with wall!');\n    }\n});\n\n// game controls\nclient.on(`interactionCreate`, async (i) =\u003e {\n    switch (i.customId) {\n        case 'up':\n            moveable.y++;\n            await update(i, plane, moveable, nonmove);\n            break;\n        case 'down':\n            moveable.y--;\n            await update(i, plane, moveable, nonmove);\n            break;\n        case 'left':\n            moveable.x--;\n            await update(i, plane, moveable, nonmove);\n            break;\n        case 'right':\n            moveable.x++;\n            await update(i, plane, moveable, nonmove);\n            break;\n        case 'end':\n            game.end(i);\n    }\n});\n\n// helper function to make this 50 less lines.\nasync function update(i, plane, ...item) {\n    /* \n        you don't need to make a function like this\n        but due to my controls doing the same thing\n        over and, over again, I made it a function.\n        */\n    await plane.update(...item);\n    await i.update({\n        embeds: [\n            new EmbedBuilder()\n                .setTitle(`g a m e`)\n                .setDescription(plane.return())\n                .setFooter({ text: `Score = ${game.var.score}` }),\n        ],\n        components: [row],\n    });\n}\n\n// Login the Discord client with your token\nclient.login('your-token-here-bro');\n```\n\nThis code sets up a Discord bot using the Discord.js library and integrates it with a game using the disgamekit library. Here's a breakdown of the major components:\n\n-   Discord.js: It's used to create the Discord client, handle events, and interact with the Discord API.\n-   disgamekit: This library.\n\nThe code initializes a game with a client, a plane, and plane objects. It also sets up game controls as buttons using an `ActionRowBuilder`.\n\nWhen a user sends a message with the command \"mjb?button\", the game starts, the plane is updated with the objects, and the game state is sent as a reply with the buttons.\n\nThe game responds to interactions with the buttons, updating the position of the moveable object and updating the game state accordingly.\n\nThe game emits events for \"start\", \"end\", and \"collision\", which can be handled to perform actions when these events occur. (Currently) the `moveable` listens for the \"collision\" event and checks whether it collided with an object or the wall. If it's the wall it logs to the console. If it's the `nonmove` object, it updates the game variables stored in `game.var`.\n\nThe `update` function is a helper function that updates the game state and updates the message with the new state and buttons.\n\n**NOTE** - The code above is set up in a way that every user plays the same game . To avoid this either initialize the variables in the message create or use a map.\n\n## ComplexPlaneObject Class\n\nLike the PlaneObject (without collision or AI), but can span multiple pixels on the plane.\nCurrently can create a line from point A to B.\n\n### Constructor\n\n#### Parameters\n\n-   `plane`: Pass the plane associated with this object, like the PlaneObject\n\n```js\nconst { ComplexPlaneObject, Plane } = require('disgamekit');\n\nconst plane = new Plane(/** Plane stuff**/);\nconst obj1 = new ComplexPlaneObject(plane);\n```\n\n### Methods\n\n#### `draw`\n\nDraw a line or multiples with one object.\n\n##### Parameters\n\n-   `...input`: Numerous Objects to be added. (Rest parameter)\n\n```js\nobj1.draw(\n    {\n        value: /* Emoji to display for the line*/,\n        path: /* Path the line should take.*/\n    },\n    {\n        value: \":apple:\",\n        path: \"0, 0 -\u003e 7, 8\" // (x1, y1 -\u003e y1, y2)\n    }\n)\n```\n\n#### `return`\n\nReturn an array of PlaneObjects that represent the line.\n\n```js\nconst plane = new Plane(/** plane stuff */);\nconst obj1 = new ComplexPlaneObject(plane);\n\nplane.update(...obj1.return()); // used a rest parameter because array.\n```\n\n## Turns Class\n\nThe Turns class manages a turn-based system for games with multiple players. It allows adding, removing, and advancing turns for players.\n\n### Constructor\n\n#### Parameters\n\n-   `...players`: Numerous players to be added\n\n```js\nconst { Turns, Player } = require('disgamekit');\n\nconst player1 = new Player('1', 'Alice');\nconst player2 = new Player('2', 'Bob');\nconst player3 = new Player('3', 'Charlie');\n\nconst turns = new Turns(player1, player2, player3);\n```\n\n### Methods\n\n#### `addPlayer`\n\nAdds a new player to the game.\n\n##### Parameters\n\n-   `player`: The player represented by the player class\n\n```js\nconst { Turns, Player } = require('disgamekit');\n\nconst player1 = new Player('1', 'Alice');\nconst player2 = new Player('2', 'Bob');\n\nconst turns = new Turns(player1);\n\nconst player3 = new Player('3', 'Charlie');\nturns.addPlayer(player3);\n```\n\n#### `removePlayer`\n\nRemoves a player from the game.\n\n##### Parameters\n\n-   `player`: The player represented by the player class\n\n```js\nconst { Turns, Player } = require('disgamekit');\n\nconst player1 = new Player('1', 'Alice');\nconst player2 = new Player('2', 'Bob');\nconst player3 = new Player('3', 'Charlie');\n\nconst turns = new Turns(player1, player2, player3);\n\nturns.removePlayer(player2);\n```\n\n#### `startTurns`\n\nStarts the turn-based game.\n\n```js\nconst { Turns, Player } = require('disgamekit');\n\nconst player1 = new Player('1', 'Alice');\nconst player2 = new Player('2', 'Bob');\n\nconst turns = new Turns(player1, player2);\n\nturns.startTurns();\n```\n\n#### `nextTurn`\n\nAdvances to the next turn.\n\n##### Parameters\n\n-   `overridePlayer`:**(optional)** Override with an additional player, making them have an extra turn\n\n```js\nconst { Turns, Player } = require('disgamekit');\n\nconst player1 = new Player('1', 'Alice');\nconst player2 = new Player('2', 'Bob');\n\nconst turns = new Turns(player1, player2);\n\nturns.startTurns();\n\nturns.nextTurn();\n```\n\n#### `reverseOrder()`\n\nReverses the order of turns.\n\n```js\nconst { Turns, Player } = require('disgamekit');\n\nconst player1 = new Player('1', 'Alice');\nconst player2 = new Player('2', 'Bob');\nconst player3 = new Player('3', 'Charlie');\n\nconst turns = new Turns(player1, player2, player3);\n\nturns.reverseOrder();\n```\n\n## Player Class\n\nThe Player class represents a player in the game (specifically for the Turns class). It holds a unique identifier (id) and the player's name (name).\n\n### Constructor\n\n#### Parameters\n\n-   `id`: The player's unique identifier.\n-   `name`: The player's name.\n\n```js\nconst { Player } = require('disgamekit');\n\nconst player1 = new Player('1', 'Alice');\nconst player2 = new Player('2', 'Bob');\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyetnt%2Fdisgamekit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyetnt%2Fdisgamekit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyetnt%2Fdisgamekit/lists"}