🛠️ 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:

Defining the physical parts in components/.
Ensuring all required hardware exists in common/hardware.json.
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.

{
  "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.

{
  "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:

"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.

"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:

Run the vendor script:
```
python scripts/vendor_update.py
```
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

Component JSON added to website/src/data/components/.
Hardware added to common/hardware.json (if new).
ID added to config/options.json.
python scripts/vendor_update.py executed.
Verified that the part appears in the summary and correctly calculates hardware.
(Optional) High-quality image added to /public/images/options/.

4.3 KiB Raw Blame History Unescape Escape