# Editable BeamNG JBeam starter files

These files are learning templates for the two interactive builds in Jack's Coaching. They are not drop-in mods: every target vehicle has different node IDs, geometry, part slots, and integration needs. Make a copy before editing.

## What is included

- `fridge-slide-starter.jbeam` — example fixed frame, paired rails, tray nodes, beams, and capped slidenodes.
- `canopy-door-starter.jbeam` — a torsion hydro, clickable `triggers2` handle, action link, and `actionsEnabled` entry.
- `canopy-door.interaction.json` — the matching version 2 interaction action that toggles the `jack_canopy` electric.

## What to edit, and with what

### Use Visual Studio Code for JBeam and interaction files

JBeam files are text files with BeamNG's JSON-like table syntax and comments. BeamNG's vehicle modding guide recommends Visual Studio Code and its JBeam extension. If you do not install the extension, set `.jbeam` files to JSONC mode so comments and syntax structure are highlighted. The interaction file is regular JSON; keep it valid JSON without comments.

Do not use Blender to edit JBeam. Use Blender to create or adjust the DAE meshes, pivots, and object names that you later reference from JBeam.

### Fridge slide: edit these first

1. In `fridge-slide-starter.jbeam`, change `authors`, `name`, and `slotType`. `slotType` must match a slot offered by the parent part on your chosen vehicle. If you are adding a new slot, you must add it safely to the parent component; do not overwrite the vehicle's original files.
2. Replace `replace_host_left_front`, `replace_host_left_rear`, `replace_host_right_front`, and `replace_host_right_rear` with real node IDs from the fixed cargo-bed or body structure. These are referenced by the attachment beams.
3. Edit the `posX`, `posY`, and `posZ` values for the `jfs_frame_*` and `jfs_tray_*` nodes. BeamNG vehicle coordinates are +X left, +Y backward, +Z up; positions are meters. Put each tray slider exactly on its rail at spawn.
4. Keep each rail ID consistent: `jfs_rail_left`/`jfs_rail_right` in `rails` must match the `railName` in `slidenodes`.
5. Tune `spring`, `strength`, and `capStrength` only after the alignment is correct. The included numbers are starting values, not universal settings. `capped: true` keeps the slider from running off the rail.
6. In Blender, make your own tray and frame meshes, then add matching flexbodies to JBeam. Keep the mesh names and node groups consistent. The starter has no DAE mesh references by design.

### Canopy door: edit these first

1. In `canopy-door-starter.jbeam`, set the author/name/slot, then replace `replace_panel_lever`, `replace_hinge_front`, `replace_hinge_rear`, and `replace_frame_lever` with actual node IDs. The middle two nodes define the hinge axis; the first and last are actuator lever ends.
2. Set the torsion hydro `factor` to the allowed hinge angle in radians, and tune `inRate`/`outRate` for speed. Reverse the sign if it rotates the wrong way. Check the panel clears the body before increasing travel.
3. Replace `replace_trigger_ref`, `replace_trigger_x`, and `replace_trigger_y` with valid nearby reference nodes. Adjust the trigger `size` and `baseTranslation` so the clickable box is over the handle.
4. Keep these three names identical in both files: action ID `jacks_canopy_toggle`, trigger link action ID, and the `actionsEnabled` row. Keep the hydro's `inputSource` `jack_canopy` matched to the electric set by the interaction action.
5. Copy `canopy-door.interaction.json` beside the vehicle's files, then change its visible `title` and `desc` if desired. Do not change `fileversion` from `2`.
6. Build the door mesh and pivot in Blender; JBeam defines the simulated nodes and movement, while Blender provides the visible mesh.

## Where to install and test

During development, work from a uniquely named folder under the BeamNG user folder's `mods/unpacked` directory and keep the vehicle folder structure intact. These templates need to be merged into a compatible vehicle part and slot before the game can use them.

After each edit, reload the vehicle with `Ctrl+R` and read the console before making more changes. Use the vehicle debug UI's Rails and Slidenodes view for the fridge slide. For the canopy, hover over the handle to confirm the trigger appears, then click it and watch the actuator. Test both features at low speed and after a gentle impact. Resolve missing-node and action-link errors before tuning strength or speed.

## BeamNG reference links

- JBeam editor recommendation: https://documentation.beamng.com/modding/vehicle/tutorials/getting_started/
- Rails and slidenodes: https://documentation.beamng.com/modding/vehicle/sections/rails/
- Rails/slidenodes debug view: https://documentation.beamng.com/modding/vehicle/intro_jbeam/debugtools/
- Torsion hydros: https://documentation.beamng.com/modding/vehicle/sections/torsionhydros/
- Triggers2: https://documentation.beamng.com/modding/vehicle/sections/triggers/triggers2/
- Interaction maps: https://documentation.beamng.com/modding/input/interaction-maps/