{"id":18817804,"url":"https://github.com/vpdb/vpx-js","last_synced_at":"2025-10-29T23:02:16.907Z","repository":{"id":34858462,"uuid":"184831663","full_name":"vpdb/vpx-js","owner":"vpdb","description":":video_game: Visual Pinball in the Browser","archived":false,"fork":false,"pushed_at":"2025-09-25T21:25:33.000Z","size":23733,"stargazers_count":58,"open_issues_count":58,"forks_count":10,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-10-08T00:53:19.275Z","etag":null,"topics":["gltf","javascript","physics-engine","pinball","pinball-simulation","visualpinball"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vpdb.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":"2019-05-03T23:27:20.000Z","updated_at":"2025-09-16T07:37:42.000Z","dependencies_parsed_at":"2023-11-16T20:24:56.888Z","dependency_job_id":null,"html_url":"https://github.com/vpdb/vpx-js","commit_stats":null,"previous_names":["vpdb/vpx-toolbox"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/vpdb/vpx-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpdb%2Fvpx-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpdb%2Fvpx-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpdb%2Fvpx-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpdb%2Fvpx-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vpdb","download_url":"https://codeload.github.com/vpdb/vpx-js/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpdb%2Fvpx-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281713535,"owners_count":26548732,"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","status":"online","status_checked_at":"2025-10-29T02:00:06.901Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["gltf","javascript","physics-engine","pinball","pinball-simulation","visualpinball"],"created_at":"2024-11-08T00:13:29.258Z","updated_at":"2025-10-29T23:02:16.889Z","avatar_url":"https://github.com/vpdb.png","language":"TypeScript","readme":"# Visual Pinball X in JavaScript\r\n\r\n*A port of the best pinball simulator out there*\r\n\r\n[![Build Status][travis-image]][travis-url]\r\n[![codecov](https://codecov.io/gh/vpdb/vpx-js/branch/master/graph/badge.svg)](https://codecov.io/gh/vpdb/vpx-js)\r\n[![Dependencies][dependencies-image]][dependencies-url]\r\n\r\n## Features\r\n\r\nThis isn't a ready-to-use game. It's a library of loosely-coupled components that\r\ntogether implement [Visual Pinball](https://sourceforge.net/projects/vpinball/)'s\r\nplayer for the web.\r\n\r\nThe player can be split into three parts:\r\n\r\n1. The rendering engine\r\n2. The physics engine\r\n3. The scripting engine\r\n\r\nThis library provides an abstraction layer for rendering with [three.js](https://threejs.org/),\r\nwhich covers the first point. A physics loop is implemented by the `Player`\r\nclass. Collision detection and rigid body dynamics are fully ported, covering the\r\nsecond part. Work on scripting has begun with the wiring set up and the default\r\ntable script working. More info about how we go about this can be found\r\n[here](https://github.com/freezy/vpweb/issues/1).\r\n\r\n### Rendering\r\n\r\nVPX-JS reads Visual Pinball's VPX format and extracts all meshes in VP's internal\r\nformat. Using an abstraction layer, any WebGL framework can convert this format\r\nand construct a scene. An adapter for three.js is included.\r\n\r\nAdditionally, VPX-JS supports direct export to [GLTF](https://www.khronos.org/gltf/)\r\nfiles, which is nice, because it allows off-loading the export to a server. It's\r\nalso nice because GLTF allows doing stuff that Visual Pinball's [OBJ](https://en.wikipedia.org/wiki/Wavefront_.obj_file)\r\nexport doesn't, for example:\r\n\r\n- Include materials, textures and lights in one single file\r\n- Apply optimizations:\r\n   - PNG textures with no transparency are converted to JPEG\r\n   - PNG textures with transparency are [PNG-crushed](https://en.wikipedia.org/wiki/Pngcrush)\r\n   - Compress meshes with [Draco](https://google.github.io/draco/)\r\n\r\n![image](https://user-images.githubusercontent.com/70426/56841267-0419fc00-688d-11e9-9996-6d84070da392.png)\r\n*A table in the browser using three.js*\r\n\r\n### Physics\r\n\r\nVPX-JS uses the same physics code than Visual Pinball. That means the gameplay\r\nis identical in the browser than when running VPX.\r\n\r\n### Scripting and VPM\r\n\r\nFor scripting, see [this issue](https://github.com/freezy/vpweb/issues/1). About\r\nVPM, there isn't a JavaScript implementation of PinMAME yet. However, @neophob\r\nwrote a [WPC emulator](https://github.com/neophob/wpc-emu) from scratch that will\r\ncover many games already.\r\n\r\n## Development Setup\r\n\r\nGiven this is a lib, you'll need an actual web application to test. There is a\r\nsimple one we're currently using for development [here](https://github.com/freezy/vpweb).\r\n\r\nThis *vpweb* project retrieves VPX-JS from NPM, so in order to iterate rapidly,\r\nwe'll link it to your local working copy.\r\n\r\n```bash\r\ngit clone https://github.com/vpdb/vpx-js.git\r\ncd vpx-js\r\nnpm ci\r\nnpm link\r\nnpm run build:watch\r\n```\r\n\r\nAnd the vpweb host application:\r\n\r\n```bash\r\ngit clone https://github.com/freezy/vpweb.git\r\ncd vpweb\r\nnpm ci\r\nnpm link vpx-js\r\nnpm start\r\n```\r\n\r\nThen connect to `http://localhost:8080` and drag a VPX file into it. Note that\r\nthe scripting engine is still limited. However, the table script of the default\r\ntable should now work.\r\n\r\n## Usage\r\n\r\nWIP. The API will be documented when it's considered stable.\r\n\r\n## Tests\r\n\r\nRun tests with:\r\n\r\n```bash\r\nnpm run test\r\n```\r\n\r\nFor more infos about how tests are written, see [here](https://github.com/vpdb/vpx-js/tree/master/test#readme)\r\n\r\n## Credits\r\n\r\n* @jsm174 for getting the Nearley grammar right and his work on translating VBScript to JavaScript\r\n* @neophob for his awesome WPC-EMU integration\r\n\r\n\u003ca title=\"IntelliJ IDEA\" href=\"https://www.jetbrains.com/idea/\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/vpdb/server/master/assets/intellij-logo-text.svg?sanitize=true\" alt=\"IntelliJ IDEA\" width=\"250\"\u003e\u003c/a\u003e\r\n\r\nSpecial thanks go to JetBrains for their awesome IDE and support of the Open Source Community!\r\n\r\n## License\r\n\r\nGPLv2, see [LICENSE](LICENSE).\r\n\r\n[travis-image]: https://img.shields.io/travis/vpdb/vpx-js/master?style=flat-square\r\n[travis-url]: https://travis-ci.org/vpdb/vpx-js\r\n[dependencies-image]: https://david-dm.org/vpdb/vpx-js.svg?style=flat-square\r\n[dependencies-url]: https://david-dm.org/vpdb/vpx-js\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvpdb%2Fvpx-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvpdb%2Fvpx-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvpdb%2Fvpx-js/lists"}