153 lines
4.3 KiB
Markdown
153 lines
4.3 KiB
Markdown
# 🛠️ Contributing to OSSM Configurator
|
||
|
||
Thank you for your interest in contributing to the OSSM Configurator! This document provides a detailed guide on how to add new components, mods, remotes, and hardware to the system.
|
||
|
||
---
|
||
|
||
## 🏗️ Data Architecture Overview
|
||
|
||
The configurator's data is organized into several key directories within `website/src/data/`:
|
||
|
||
- `common/`: Shared data like `colors.json` and `hardware.json`.
|
||
- `components/`: Detailed definitions of physical parts (STLs, quantities, dependencies).
|
||
- `config/`: Wizard configuration, including `options.json` which defines the UI structure.
|
||
|
||
---
|
||
|
||
## ➕ Adding a New Component (Mod, Remote, or Part)
|
||
|
||
Adding a component involves three main steps:
|
||
1. Defining the physical parts in `components/`.
|
||
2. Ensuring all required hardware exists in `common/hardware.json`.
|
||
3. Linking the component into the wizard UI via `config/options.json`.
|
||
|
||
### Step 1: Define the Component
|
||
Components are defined as JSON objects. A component can use one of two structures:
|
||
|
||
#### A. Standard Component (e.g., `actuator.json`)
|
||
Used for fixed assemblies where all selected parts are gathered into a single list.
|
||
|
||
```json
|
||
{
|
||
"my-new-mod": {
|
||
"category": "Mods",
|
||
"type": "mod",
|
||
"printedParts": [
|
||
{
|
||
"id": "mod-part-a",
|
||
"name": "Mod Part A",
|
||
"filamentEstimate": 45.2,
|
||
"timeEstimate": "1h30m",
|
||
"colour": "primary",
|
||
"required": true,
|
||
"url": "https://github.com/Owner/Repo/blob/main/part-a.stl?raw=true"
|
||
}
|
||
],
|
||
"hardwareParts": [
|
||
{
|
||
"id": "hardware-fasteners-m3x8-shcs",
|
||
"required": true,
|
||
"quantity": 4,
|
||
"relatedParts": ["mod-part-a"]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### B. System-based Component (e.g., `remote.json`, `hinges.json`)
|
||
Used when a category has multiple distinct "systems" that a user chooses between.
|
||
|
||
```json
|
||
{
|
||
"remotes": {
|
||
"category": "Remote",
|
||
"systems": {
|
||
"my-custom-remote": {
|
||
"name": "Custom Remote v1",
|
||
"description": "A high-performance custom remote",
|
||
"image": "/images/options/custom-remote.png",
|
||
"bodyParts": [
|
||
{
|
||
"id": "remote-shell",
|
||
"name": "Remote Shell",
|
||
"url": "...",
|
||
"required": true
|
||
}
|
||
],
|
||
"knobs": [
|
||
{ "id": "knob-standard", "name": "Standard Knob", "url": "..." }
|
||
],
|
||
"hardwareParts": [
|
||
{ "id": "remote-hardware", "required": true }
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Step 2: Register Hardware
|
||
If your component requires hardware not already in the system, add it to `website/src/data/common/hardware.json`:
|
||
|
||
```json
|
||
"fasteners": {
|
||
"M3x12 SHCS": {
|
||
"id": "hardware-fasteners-m3x12-shcs",
|
||
"name": "M3x12 SHCS",
|
||
"price": 0.15
|
||
}
|
||
}
|
||
```
|
||
|
||
### Step 3: Add to the Wizard (options.json)
|
||
To make your part selectable, add its ID to the `sections` in `website/src/data/config/options.json`.
|
||
|
||
```json
|
||
"toyMounts": {
|
||
"sections": {
|
||
"myNewCategory": {
|
||
"title": "My New Category",
|
||
"componentIds": ["my-new-part-id"],
|
||
"isMultiSelect": true
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 The Vendor System
|
||
|
||
The configurator uses a script to "vendor" external files. This ensures that even if an upstream GitHub repo changes, our builds remain stable.
|
||
|
||
After adding a new component with a `url` field:
|
||
1. Run the vendor script:
|
||
```bash
|
||
python scripts/vendor_update.py
|
||
```
|
||
2. The script will:
|
||
- Download the file to the `vendor/` directory.
|
||
- Calculate a checksum.
|
||
- Pin it to the current commit SHA.
|
||
- Update your component JSON with a `vendor` metadata block.
|
||
|
||
---
|
||
|
||
## 🖼️ Images & Assets
|
||
|
||
- **Component Images**: Place images in `website/public/images/options/`.
|
||
- **Naming**: Use the component `id` as the filename (e.g., `my-part-id.png`).
|
||
- **Specs**: Transparent PNGs are preferred for a premium "floating" look.
|
||
|
||
---
|
||
|
||
## ✅ Contribution Checklist
|
||
|
||
1. [ ] Component JSON added to `website/src/data/components/`.
|
||
2. [ ] Hardware added to `common/hardware.json` (if new).
|
||
3. [ ] ID added to `config/options.json`.
|
||
4. [ ] `python scripts/vendor_update.py` executed.
|
||
5. [ ] Verified that the part appears in the summary and correctly calculates hardware.
|
||
6. [ ] (Optional) High-quality image added to `/public/images/options/`.
|