diff --git a/fission/README.md b/fission/README.md index fc4098ecc..6d8a493e8 100644 --- a/fission/README.md +++ b/fission/README.md @@ -1,14 +1,31 @@ -# Fission: Synthesis' web-based robot simulator +# Fission -## Gettings Started +Fission is Synthesis' web-based robotics simulator. This app is hosted [on our website](https://synthesis.github.com/fission/), in addition to a closed, in-development version [here](https://synthesis.autodesk.com/beta/). +## Setup & Building ### Requirements 1. NPM (v10.2.4 recommended) + - Yarn, Bun, or any other package managers work just as well. 2. NodeJS (v20.10.0 recommended) -3. TypeScript (v4.8.4 recommended) _Unknown if this is actually required_ + - Needed for running the development server. -### Assets +### Setup + +You can either run the `init` command or run the following commands details in "Specific Steps": + +```bash +npm i && npm init +``` + +
+Specific Steps + +To install all dependencies: + +```bash +npm i +``` For the asset pack that will be available in production, download the asset pack [here](https://synthesis.autodesk.com/Downloadables/assetpack.zip) and unzip it. Make sure that the Downloadables directory is placed inside of the public directory like so: @@ -19,50 +36,63 @@ Make sure that the Downloadables directory is placed inside of the public direct This can be accomplished with the `assetpack` npm script: -``` +```bash npm run assetpack ``` -### Building - -To build, install all dependencies: +We use [Playwright](https://playwright.dev/) for testing consistency. The package is installed with the rest of the dependencies; however, be sure to install the playwright browsers with the following command: ```bash -npm i +npx playwright install +``` +or +```bash +npm run playwright:install ``` -### NPM Scripts - -| Script | Description | -| -------------- | ----------------------------------------------------------------------------------------------------------------------- | -| `dev` | Starts the development server used for testing. Supports hotloading (though finicky with WASM module loading). | -| `test` | Runs the unit tests via vitest. | -| `build` | Builds the project into it's packaged form. Uses root base path. | -| `build:prod` | Builds the project into it's packaged form. Uses the `/fission/` base path. | -| `preview` | Runs the built project for preview locally before deploying. | -| `lint` | Runs eslint on the project. | -| `lint:fix` | Attempts to fix issues found with eslint. | -| `prettier` | Runs prettier on the project as a check. | -| `prettier:fix` | Runs prettier on the project to fix any issues with formating. **DO NOT USE**, I don't like the current format it uses. | -| `format` | Runs `prettier:fix` and `lint:fix`. **Do not use** for the same reasons as `prettier:fix`. | -| `assetpack` | Downloads the assetpack and unzips/installs it in the correct location. | -| `playwright:install` | Downloads the playwright browsers. | +
-### Unit Testing +### Environment Configuration -We use [Playwright](https://playwright.dev/) for testing consistency. The package is installed with the rest of the dependencies; however, be sure to install the playwright browsers with the following command: +In `vite.config.ts` you'll find a number of constants that can be used to tune the project to match your development environment. +## Running & Testing + +### Development Server + +You can use the `dev` command to run the development server. This will open a server on port 3000 and open your default browser at the hosted endpoint. + +```bash +npm run dev ``` -npx playwright install + +### Unit Testing + +We use a combination of Vitest and Playwright for running our unit tests. A number of the unit tests rely on the asset pack data and may time out due to download speeds. By default, the unit test command uses a Chromium browser. + +```bash +npm run test ``` -or + +## Packaging + +We have two packaging commands: one for compiling dev for attachment to the in-development endpoint, and another for the release endpoint. + +Release: +```bash +npm run build:prod ``` -npm run playwright:install + +In-development: +```bash +npm run build:dev ``` -### Autodesk Platform Services +You can alternatively run the default build command for your own hosting: -To test/enable the use of Autodesk Platform Services (APS), please follow instructions for development web server (Closed Source). +```bash +npm run build +``` ## Core Systems @@ -75,16 +105,18 @@ The world serves as a hub for all of the core systems. It is a static class that ### Scene Renderer -The Scene Renderer is our interface with rendering within the Canvas. This is primarily done via ThreeJS, however can be extended later on. +The Scene Renderer is our interface for rendering within the Canvas. This is primarily done via ThreeJS, however it can be extended later on. ### Physics System -This Physics System is our interface with Jolt, ensuring objects are properly handled and provides utility functions that are more custom fit to our purposes. +This Physics System is our interface with Jolt, ensuring objects are properly handled and providing utility functions that are more custom-fit to our purposes. [Jolt Physics Architecture](https://jrouwe.github.io/JoltPhysics/) ### Input System +The Input System listens for and records key presses and joystick positions to be used by robots. It also maps robot behaviors (e.g. an arcade drivetrain or an arm) to specific keys through customizable input schemes. + ### UI System ## Additional Systems @@ -93,11 +125,11 @@ These systems will extend off of the core systems to build out features in Synth ### Simulation System -The Simulation System articulates dynamic elements of the scene via the Physics System. At it's core there are 3 main components: +The Simulation System articulates dynamic elements of the scene via the Physics System. At its core there are 3 main components: #### Driver -Drivers are mostly write-only. They take in values to know how to articulate the physics objects and contraints. +Drivers are mostly write-only. They take in values to know how to articulate the physics objects and constraints. #### Stimulus @@ -107,6 +139,22 @@ Stimuli are mostly read-only. They read values from given physics objects and co Brains are the controllers of the mechanisms. They use a combination of Drivers and Stimuli to control a given mechanism. -For basic user control of the mechanisms, we'll have a Synthesis Brain. By the end of Summer 2024, I hope to have an additional brain, the WPIBrain for facilitating WPILib code control over the mechanisms inside of Synthesis. - -### Mode System +For basic user control of the mechanisms, we'll have a Synthesis Brain. We hope to have an additional brain by the end of Summer 2024: the WPIBrain for facilitating WPILib code control over the mechanisms inside of Synthesis. + +## NPM Scripts + +| Script | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `init` | Runs the initialization commands to install all dependencies, assets, and unit testing browsers. | +| `dev` | Starts the development server used for testing. Supports hot-reloading (though finicky with WASM module loading). | +| `test` | Runs the unit tests via Vitest. | +| `build` | Builds the project into its packaged form. Uses the root base path. | +| `build:prod` | Builds the project into its packaged form. Uses the `/fission/` base path. | +| `preview` | Runs the built project for preview locally before deploying. | +| `lint` | Runs ESLint on the project. | +| `lint:fix` | Attempts to fix issues found with ESLint. | +| `prettier` | Runs Prettier on the project as a check. | +| `prettier:fix` | Runs Prettier on the project to fix any issues with formatting. | +| `format` | Runs `prettier:fix` and `lint:fix`. | +| `assetpack` | Downloads the assetpack and unzips/installs it in the correct location. | +| `playwright:install` | Downloads the Playwright browsers. | diff --git a/fission/package.json b/fission/package.json index 0643c80a5..0e67a1163 100644 --- a/fission/package.json +++ b/fission/package.json @@ -4,6 +4,7 @@ "version": "0.0.1", "type": "module", "scripts": { + "init": "(bun run assetpack && bun run playwright:install) || (npm run assetpack && npm run playwright:install)", "dev": "vite --open", "build": "tsc && vite build", "build:prod": "tsc && vite build --base=/fission/ --outDir dist/prod", @@ -74,5 +75,9 @@ "vite-plugin-glsl": "^1.3.0", "vite-plugin-singlefile": "^0.13.5", "vitest": "^1.5.3" + }, + "license": "Apache-2.0", + "repository": { + "url": "https://github.com/Autodesk/synthesis.git" } }