{"id":21025569,"url":"https://github.com/robertcorponoi/pixi-matter","last_synced_at":"2025-05-15T10:31:04.642Z","repository":{"id":48993918,"uuid":"318933821","full_name":"robertcorponoi/pixi-matter","owner":"robertcorponoi","description":"Easily create pixi sprites and graphics objects with matter physics bodies.","archived":false,"fork":false,"pushed_at":"2023-04-07T00:47:43.000Z","size":1226,"stargazers_count":7,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-13T04:00:10.114Z","etag":null,"topics":["graphics","matter","matter-js","physics","pixi","pixi-js","pixijs","sprite","sprites"],"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/robertcorponoi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-06T02:27:26.000Z","updated_at":"2023-06-16T06:26:32.000Z","dependencies_parsed_at":"2024-11-14T22:34:58.050Z","dependency_job_id":"93f63152-606e-48fc-946a-f842dadad2d1","html_url":"https://github.com/robertcorponoi/pixi-matter","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertcorponoi%2Fpixi-matter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertcorponoi%2Fpixi-matter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertcorponoi%2Fpixi-matter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertcorponoi%2Fpixi-matter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robertcorponoi","download_url":"https://codeload.github.com/robertcorponoi/pixi-matter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254322790,"owners_count":22051665,"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":["graphics","matter","matter-js","physics","pixi","pixi-js","pixijs","sprite","sprites"],"created_at":"2024-11-19T11:34:30.897Z","updated_at":"2025-05-15T10:31:04.360Z","avatar_url":"https://github.com/robertcorponoi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg width=\"250\" height=\"250\" src=\"https://github.com/robertcorponoi/graphics/blob/master/pixi-matter/logo/logo.png?raw=true\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ePixiMatter\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003eEasily create pixi sprites and graphics objects with matter physics bodies.\u003cp\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![NPM version](https://img.shields.io/npm/v/pixi-matter.svg?style=flat)](https://www.npmjs.com/package/pixi-matter)\n[![Known Vulnerabilities](https://snyk.io/test/github/robertcorponoi/pixi-matter/badge.svg)](https://snyk.io/test/github/robertcorponoi/pixi-matter)\n![npm](https://img.shields.io/npm/dt/pixi-matter)\n[![NPM downloads](https://img.shields.io/npm/dm/pixi-matter.svg?style=flat)](https://www.npmjs.com/package/pixi-matter)\n\u003ca href=\"https://badge.fury.io/js/pixi-matter\"\u003e\u003cimg src=\"https://img.shields.io/github/issues/robertcorponoi/pixi-matter.svg\" alt=\"issues\" height=\"18\"\u003e\u003c/a\u003e\n\u003ca href=\"https://badge.fury.io/js/pixi-matter\"\u003e\u003cimg src=\"https://img.shields.io/github/license/robertcorponoi/pixi-matter.svg\" alt=\"license\" height=\"18\"\u003e\u003c/a\u003e\n\n\u003c/div\u003e\n\n## **Table of Contents**\n\n-   [Installation](#installation)\n-   [Usage](#usage)\n-   [PixiMatter](#piximatter)\n-   [PhysicsSprite](#physicssprite)\n    -   [SpriteOptions](#spriteoptions)\n-   [PhysicsGraphics](#physicsgraphics)\n    -   [GraphicsOptions](#graphicsoptions)\n-   [Examples](#examples)\n\n## **Installation**\n\nTo install this module through npm, use:\n\n```\n$ npm install pixi-matter\n```\n\n## **Usage**\n\n`pixi-matter` consists of a main module that manages the running and updating of the matter engine and options modules that are used to create the pixi physics objects.\n\nAn example of a simple setup can be seen below, if you want to see specifics check out the [PixiMatter](#piximatter), [PhysicsSprite](#physicssprite), and [PhysicsGraphics](#physicsgraphics) sections.\n\n```js\nimport { PixiMatter, PhysicsSprite } from \"pixi-matter\";\n\n// Create your PIXI Application however you wish and add it to the document.\nconst app = new PIXI.Application({\n    width: 800,\n    height: 600,\n    backgroundColor: 0x000000,\n});\ndocument.body.appendChild(app.view);\n\n// Create a new instance of PixiMatter.\nconst pixiMatter = new PixiMatter();\n\n// For this example we load up a rectangular and circular sprite, respectively.\napp.loader.add(\"elephant\", \"assets/elephant.png\");\napp.loader.add(\"giraffe\", \"assets/giraffe.png\");\n\napp.loader.add((loader, resources) =\u003e {\n    // Create two sprites from the elephant texture and one sprite from the giraffe texture loaded.\n    // Take note that the first parameter is the texture, the second is an object where you have to\n    // specify the sprite's options, and the third is the options for the physics body of the sprite.\n    const elephant1 = new PhysicsSprite(\n        resources.elephant.texture,\n        { x: 200, y: 100, width: 60, height: 60 },\n        { frictionAir: 0.001 },\n    );\n    const elephant2 = new PhysicsSprite(\n        resources.elephant.texture,\n        { x: 400, y: 100, width: 60, height: 60 },\n        { frictionAir: 0.05 },\n    );\n    const giraffe = new PhysicsSprite(\n        resources.elephant.texture,\n        { x: 600, y: 100, width: 60, isCircle: true },\n        { frictionAir: 0.1 },\n    );\n\n    // Add the sprites to the matter world so that they can be updated by the physics engine.\n    pixiMatter.addToWorld(elephant1, elephant2, giraffe);\n\n    // Add the sprites to the the renderer using pixi.\n    app.stage.addChild(elephant1, elephant2, giraffe);\n});\n\n// Add the `update` method to the pixi ticker or custom animation function so that the position\n// and rotation of the sprites added can be updated to match the position and rotation of their\n// physics bodies.\napp.ticker.add(() =\u003e pixiMatter.update());\n```\n\n## **PixiMatter**\n\nThe PixiMatter module is used to manage the Matter engine and world.\n\n## **Properties**\n\n### **engine**\n\nThe Matter engine.\n\n**example:**\n\n```js\nimport { PixiMatter } from \"pixi-matter\";\n\nconst pixiMatter = new PixiMatter();\nconst engine = pixiMatter.engine;\n```\n\n### **pixiObjects**\n\nContains all of the pixi objects that have been added to the Matter world.\n\n**example:**\n\n```js\nimport { PixiMatter } from \"pixi-matter\";\n\nconst pixiMatter = new PixiMatter();\nconst pixiObjects = pixiMatter.pixiObjects;\n```\n\n## **Methods**\n\n### **update**\n\nUpdates the position and rotation of each pixi object added to the world according to where its physics body is. This needs to be called in the game loop of your application.\n\n**example:**\n\n```js\nimport { PixiMatter } from \"pixi-matter\";\n\nconst app = new PIXI.Application();\nconst pixiMatter = new PixiMatter();\n\n// Every tick PixiMatter will update the positions of objects added to match the positions of their physics bodies.\napp.ticker.add(() =\u003e pixiMatter.update());\n```\n\n### **addToWorld**\n\nAdds one or more pixi objects to the Matter world so that their positions can be updated.\n\n| Name           | Type                             | Description                                  | Default |\n| -------------- | -------------------------------- | -------------------------------------------- | ------- |\n| ...pixiObjects | PhysicsSprite[] GraphicsSprite[] | The pixi object/s to add to the Matter world |         |\n\n**example:**\n\n```js\nimport { PixiMatter, PhysicsSprite, PhysicsGraphics } from \"pixi-matter\";\n\nconst app = new PIXI.Application();\nconst pixiMatter = new PixiMatter();\n\nconst player = new PhysicsSprite(\n    resources.elephant.texture,\n    { x: 200, y: 100, width: 60, height: 60 },\n    { frictionAir: 0.001 },\n);\nconst ground = new PhysicsGraphics(\n    { x: 0, y: 0, width: 800, height: 50 },\n    { isStatic: true },\n);\n\n// The `player` and `ground` objects will now be updated by the Matter engine.\npixiMatter.addToWorld(player, ground);\n```\n\n## **removeFromWorld**\n\nRemoves one or more pixi objects from the Matter world.\n\n| Name           | Type                             | Description                                       | Default |\n| -------------- | -------------------------------- | ------------------------------------------------- | ------- |\n| ...pixiObjects | PhysicsSprite[] GraphicsSprite[] | The pixi object/s to remove from the Matter world |         |\n\n**example:**\n\n```js\nimport { PixiMatter, PhysicsSprite, PhysicsGraphics } from \"pixi-matter\";\n\nconst app = new PIXI.Application();\nconst pixiMatter = new PixiMatter();\n\nconst player = new PhysicsSprite(\n    resources.elephant.texture,\n    { x: 200, y: 100, width: 60, height: 60 },\n    { frictionAir: 0.001 },\n);\nconst ground = new PhysicsGraphics(\n    { x: 0, y: 0, width: 800, height: 50 },\n    { isStatic: true },\n);\n\n// The `ground` object is now no longer updated by the Matter engine.\npixiMatter.removeFromWorld(ground);\n```\n\n## **PhysicsSprite**\n\nThe PhysicsSprite module is used to create pixi sprites with physics bodies attached. To create a PhysicsSprite, you need to provide a texture, optional sprite options, and optional physics options.\n\n| Name           | Type                   | Description                                                | Default                         |\n| -------------- | ---------------------- | ---------------------------------------------------------- | ------------------------------- |\n| texture        | PIXI.Texture           | The texture of the sprite                                  |                                 |\n| spriteOptions  | SpriteOptions          | The options to define the initial properties of the sprite | { x: 0, y: 0, isCircle: false } |\n| physicsOptions | Matter.IBodyDefinition | The options to apply to the sprite's body.                 |                                 |\n\n### **SpriteOptions**\n\nThe following options available to set for SpriteOptions:\n\n| Name     | Type    | Description                                                    | Default |\n| -------- | ------- | -------------------------------------------------------------- | ------- |\n| x        | number  | The initial x position of the sprite.                          | 0       |\n| y        | number  | The initial y position of the sprite.                          | 0       |\n| width    | number  | The width of the sprite and the sprite's physics body.         | 0       |\n| height   | number  | The height of the sprite and the sprite's physics body.        | 0       |\n| isCircle | boolean | Indicates whether the sprite's body should be circular or not. | false   |\n\n### **PhysicsOptions**\n\nThe PhysicsOptions are no different than the options that can be passed to a Matter body so for the properties available check the [Matter body documentation](https://brm.io/matter-js/docs/classes/Body.html).\n\n**examples:**\n\n```js\nimport { PhysicsSprite } from \"pixi-matter\";\n\n// Creates a sprite with all of the default values.\nconst player = new PhysicsSprite(playerTexture);\n\n// Creates a sprite with an initial position of (200, 100) and a width/height of 60 and sets its body to have a `frictionAir` value of 0.001.\nconst player = new PhysicsSprite(\n    playerTexture,\n    { x: 200, y: 100, width: 60, height: 60 },\n    { frictionAir: 0.001 },\n);\n\n// Creates a circular sprite with a circular physics body.\nconst player = new PhysicsSprite(playerTexture, { width: 100, isCircle: true });\n```\n\n## **Properties**\n\n### **physicsOptions**\n\nThe Matter physics options for the sprite's body.\n\n**example:**\n\n```js\nimport { PhysicsSprite } from \"pixi-matter\";\n\nconst player = new PhysicsSprite(\n    resources.elephant.texture,\n    { x: 200, y: 100, width: 60, height: 60 },\n    { frictionAir: 0.001 },\n);\n\n// Contains the default physics options with the custom `frictionAir` value of 0.001.\nconst physicsOptions = player.physicsOptions;\n```\n\n### **body**\n\nThe Matter physics body of the sprite.\n\n**example:**\n\n```js\nimport { PhysicsSprite } from \"pixi-matter\";\n\nconst player = new PhysicsSprite(\n    resources.elephant.texture,\n    { x: 200, y: 100, width: 60, height: 60 },\n    { frictionAir: 0.001 },\n);\nconst body = player.body;\n```\n\n## **PhysicsGraphics**\n\nThe PhysicsGraphics module is used to create a PIXI.Graphics object with a physics body attached to it. To create a PhysicsGraphics object, you need to specify the options for it and optionally you can change the physics options of its body.\n\n| Name            | Type            | Description                                                                 | Default                                                                                    |\n| --------------- | --------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |\n| graphicsOptions | GraphicsOptions | The options for the appearance and initial position of the graphics object. | { x: 0, y: 0, width: 100, height: 100, fill: 0x000000, lineWidth: 1, lineColor: 0xffffff } |\n| physicsOptions  | PhysicsOptions  | The options to apply to the graphic object's physics body.                  |                                                                                            |\n\n### **GraphicsOptions**\n\n| Name      | Type   | Description                                                                            | Default  |\n| --------- | ------ | -------------------------------------------------------------------------------------- | -------- |\n| x         | number | The initial x position of the graphics object.                                         | 0        |\n| y         | number | The initial y position of the graphics object.                                         | 0        |\n| width     | number | If the shape is a rectangle, this is the width of the rectangle and its physics body.  | 100      |\n| height    | number | If the shape is a rectangle, this is the height of the rectangle and its physics body. | 100      |\n| radius    | number | If the shape is a circle, this is the radius of the circle.                            |          |\n| fill      | number | The color of the fill of the graphics object.                                          | 0x000000 |\n| lineWidth | number | The thickness of the graphic object's line.                                            | 1        |\n| lineColor | number | The color of the line of the graphic object.                                           | 0xffffff |\n\n### **PhysicsOptions**\n\nThe PhysicsOptions are no different than the options that can be passed to a Matter body so for the properties available check the [Matter body documentation](https://brm.io/matter-js/docs/classes/Body.html).\n\n**examples:**\n\n```js\nimport { PhysicsGraphics } from \"pixi-matter\";\n\n// Creating a PhysicsGraphics object with the default paramters.\nconst wall = new PhysicsGraphics();\n\n// Creating a PhysicsGraphics object with a starting position, custom dimensions, and a static physics body.\nconst wall = new PhysicsGraphics(\n    { x: 10, y: 10, width: 800, height: 50 },\n    { isStatic: true },\n);\n\n// Creating a PhysicsGraphics object with a circular body.\nconst ball = new PhysicsGraphics({ x: 50, y: 50, radius: 100 });\n```\n\n## **Properties**\n\n### **graphicsOptions**\n\nThe graphics options of the graphics object.\n\n**example:**\n\n```js\nimport { PhysicsGraphics } from \"pixi-matter\";\n\nconst wall = new PhysicsGraphics(\n    { x: 10, y: 10, width: 800, height: 50 },\n    { isStatic: true },\n);\n\n// Contains the custom position and width and height of the wall.\nconst graphicsOptions = wall.graphicsOptions;\n```\n\n### **physicsOptions**\n\nThe Matter physics options for the graphics object's body.\n\n**example:**\n\n```js\nimport { PhysicsGraphics } from \"pixi-matter\";\n\nconst wall = new PhysicsGraphics(\n    { x: 10, y: 10, width: 800, height: 50 },\n    { isStatic: true },\n);\n\n// Contains the default physics options of the graphics object's body along with the custom `isStatic` value of true.\nconst physicsOptions = wall.physicsOptions;\n```\n\n### **body**\n\nThe Matter physics body of the graphics object.\n\n**example:**\n\n```js\nimport { PhysicsGraphics } from \"pixi-matter\";\n\nconst wall = new PhysicsGraphics(\n    { x: 10, y: 10, width: 800, height: 50 },\n    { isStatic: true },\n);\n\nconst body = wall.body;\n```\n\n## **Examples**\n\nTo run the examples for `pixi-matter`, first you have to start the localhost server with:\n\n```bash\n$ npm run examples\n```\n\nthen you will need to navigate to https://localhost:3000 in your browser to run all of the available examples.\n\n## **License**\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobertcorponoi%2Fpixi-matter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobertcorponoi%2Fpixi-matter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobertcorponoi%2Fpixi-matter/lists"}