Skip to content

Commit

Permalink
Fission README.md and package.json updates (#1090)
Browse files Browse the repository at this point in the history
  • Loading branch information
@HunterBarclay
HunterBarclay authored Aug 21, 2024
2 parents 1473f05 + fd08bf4 commit fa453d7
Show file tree
Hide file tree
Showing 2 changed files with 92 additions and 39 deletions.
126 changes: 87 additions & 39 deletions fission/README.md
View file
Original file line number Diff line number Diff line change
@@ -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
```

<details>
<summary>Specific Steps</summary>

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:
Expand All @@ -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. |
</details>

### 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

Expand All @@ -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
Expand All @@ -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

Expand All @@ -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. |
5 changes: 5 additions & 0 deletions fission/package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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"
}
}

0 comments on commit fa453d7

Please sign in to comment.