How to Set Up Physical Chains and Ropes

ACTION GAME MAKER Module / Plugin Hub
1

How to Set Up Physical Chains/Ropes

This guide explains in detail how to set up physical chains (ropes or chains).

Table of Contents

  1. Understanding Basic Chain Structure
  2. Manual Setup
  3. Automatic Setup (Using ChainJointSetupTool)
  4. Setting Up the Visualization System
  5. Setting Up Joint Monitoring
  6. Common Setup Patterns
  7. Troubleshooting

1. Understanding Basic Chain Structure

Chain Components

A chain consists of the following elements:

  1. RigidBody2D: Each link (segment) of the chain
  2. GrooveJoint2D or PinJoint2D: Connections between links
  3. seg nodes: Connection point markers (Node2D) within each RigidBody2D
  4. BreakableJointMonitor2D: Monitors joint breakage
  5. ChainPathBinder2D: Visualizes the chain shape as a Path2D
  6. PathRibbonMesh2D: Renders the Path2D as a ribbon mesh

Example Node Structure

ChainRoot (Node2D)
├── RigidBody2D1
│   ├── CollisionShape2D
│   ├── Sprite2D
│   ├── seg1 (Node2D, position: 0, -10)
│   └── seg2 (Node2D, position: 0, 10)
├── RigidBody2D2
│   ├── GrooveJoint2D (connected to RigidBody2D1)
│   ├── CollisionShape2D
│   ├── Sprite2D
│   ├── seg1
│   └── seg2
├── RigidBody2D3
│   └── ...
└── ...

2. Manual Setup

2-1. Creating a Basic Chain

Step 1: Create the Chain Root Node

  1. Place a Node2D in the scene (e.g., ChainRoot)
  2. This node will be the parent of the chain

Step 2: Place RigidBody2D nodes

  1. Place multiple RigidBody2D nodes as children of ChainRoot
  2. Name each RigidBody2D (e.g., Link1, Link2, Link3…)
  3. Set the position of each RigidBody2D (if arranging vertically: place them at appropriate intervals according to the length of each link)

Step 3: Add CollisionShape2D and Sprite2D

  1. Add a CollisionShape2D as a child of each RigidBody2D
  2. Set the Shape to RectangleShape2D or CapsuleShape2D
  3. Add a Sprite2D as a child of each RigidBody2D (optional)
  4. Set the texture

Step 4: Create seg nodes

  1. Add a Node2D as a child of each RigidBody2D
  2. Name the first node seg1 and set its position to (0, -10)
  3. Name the second node seg2 and set its position to (0, 10)
    • These are markers for connection points
    • seg1 represents the upper connection point, seg2 represents the lower connection point

Step 5: Place GrooveJoint2D

  1. Add a GrooveJoint2D as a child of each RigidBody2D starting from the second one
  2. Configure each GrooveJoint2D:
    • position: (0, -16) (near the top edge of RigidBody2D)
    • node_a: Path to the previous RigidBody2D (e.g., ../../RigidBody2D)
    • node_b: .. (its own RigidBody2D)
    • bias: 0.9 (stiff connection) or 0.2 (loose connection)
    • length: 8.0 (groove length)
    • initial_offset: 1.0 or 2.0 (initial offset)

Step 6: Fix the Head and Tail (Optional)

  1. To fix the head:

    • Place a StaticBody2D
    • Add a GrooveJoint2D as its child
    • node_a: .. (the StaticBody2D itself)
    • node_b: Path to the first RigidBody2D (e.g., ../../Node2D/RigidBody2D)

  2. To fix the tail:

    • Similarly, place a StaticBody2D and GrooveJoint2D

Example of Completion

ChainRoot (Node2D)
├── RigidBody2D1
│   ├── CollisionShape2D
│   ├── Sprite2D
│   ├── seg1 (Node2D, position: 0, -10)
│   └── seg2 (Node2D, position: 0, 10)
├── RigidBody2D2
│   ├── GrooveJoint2D
│   │   ├── node_a: ../../RigidBody2D1
│   │   ├── node_b: ..
│   │   ├── position: (0, -16)
│   │   ├── bias: 0.9
│   │   ├── length: 8.0
│   │   └── initial_offset: 1.0
│   ├── CollisionShape2D
│   ├── Sprite2D
│   ├── seg1
│   └── seg2
└── ...

3. Automatic Setup (Using ChainJointSetupTool)

3-1. Basic Automatic Setup

Step 1: Create the Chain Root Node

  1. Place a Node2D in the scene (e.g., ChainRoot)

Step 2: Place RigidBody2D nodes

  1. Place multiple RigidBody2D nodes as children of ChainRoot
  2. Add CollisionShape2D and Sprite2D to each RigidBody2D
  3. Set their positions appropriately

Step 3: Place ChainJointSetupTool

  1. Place a Node as a parent of ChainRoot (or anywhere else)
  2. Attach chain_setup_tool.gd
  3. Configure the following in the Inspector:
    • target_parent: NodePath to ChainRoot
    • joint_type: GROOVE (recommended) or PIN
    • auto_create_seg_nodes: true (automatically generate seg nodes)
    • auto_setup_all: true (automatically set up all systems)

Step 4: Run the Setup

  1. Check the _setup_button in the Inspector
  2. Or call setup_chain() from the script
  3. It will execute automatically in the editor

What is Automatically Generated

  • If auto_setup_all=true:
    • seg1 and seg2 nodes are generated for each RigidBody2D
    • GrooveJoint2D (or PinJoint2D) is generated for each RigidBody2D
    • BreakableJointMonitor2D is generated
    • ChainPathBinder2D is generated
    • Path2D is generated
    • PathRibbonMesh2D is generated

3-2. Detailed Settings

GrooveJoint2D Settings

Property Description Recommended Value
groove_length Groove length 8.0
groove_initial_offset Initial offset 1.0 or 2.0
groove_joint_position_local Joint position (0, -16)
bias Connection stiffness 0.9 (stiff) or 0.2 (loose)
disable_collision Disable collision false (usually enabled)

seg Node Settings

Property Description Recommended Value
auto_create_seg_nodes Automatically generate seg nodes true
seg_node_prefix Prefix for seg nodes “seg”
seg1_position_local Position of seg1 (0, -10)
seg2_position_local Position of seg2 (0, 10)

Automatic Setup Settings

Property Description Recommended Value
auto_setup_all Automatically set up all systems true
auto_connect_breakable_monitor Automatically connect BreakableJointMonitor2D true
auto_setup_chain_binder Automatically configure ChainPathBinder2D true
setup_on_ready Automatically set up on ready false (usually manual execution)

4. Setting Up the Visualization System

4-1. Configuring ChainPathBinder2D

Step 1: Place ChainPathBinder2D

  1. Place a Node on the chain’s root node (or its parent)
  2. Attach chain_path_binder.gd

Step 2: Basic Settings

  1. Set auto_detect_mode to true (automatic detection mode)
  2. Set search_root to the NodePath of the chain’s root node (e.g., ../ChainRoot)
  3. Add NodePath to output_paths (a Path2D) (if empty, it will be generated automatically)

Step 3: Optional Settings

Property Description Recommended Value
auto_update Automatic update true
update_in_physics Update in physics frames true
enable_smooth_handles Smooth Curve2D true
smooth_handle_strength_px Handle strength 2.0 to 12.0
resample_spacing_px Resample points at fixed intervals 0.0 (disabled) or 8.0

4-2. Configuring PathRibbonMesh2D

Step 1: Place PathRibbonMesh2D

  1. Place a Node2D on the chain’s root node (or its parent)
  2. Attach path_ribbon_mesh_2d.gd

Step 2: Basic Settings

  1. Add NodePath to path_nodes (e.g., [NodePath("../Path2D")])
  2. Set width to the ribbon width (e.g., 20.0)
  3. Set ribbon_texture to a texture (e.g., chain.png, rope.png)

Step 3: Optional Settings

Property Description Recommended Value
width_curve Width curve Curve resource
upper_width_curve Upper width curve Curve resource
lower_width_curve Lower width curve Curve resource
thickness_domain_mode Thickness domain mode 0 (normal)

4-3. Creating Path2D

In case of automatic generation

  • If output_paths of ChainPathBinder2D is empty, a Path2D is automatically generated

In case of manual creation

  1. Place a Path2D on the chain’s root node (or its parent)
  2. A Curve2D is automatically created
  3. Add it to output_paths of ChainPathBinder2D

5. Setting Up Joint Monitoring

5-1. Configuring BreakableJointMonitor2D

Step 1: Place BreakableJointMonitor2D

  1. Place a Node on the chain’s root node (or its parent)
  2. Attach breakable_joint_monitor_2d.gd

Step 2: Basic Settings

  1. Set search_root to the NodePath of the root node to monitor (e.g., ../ChainRoot)
  2. Set auto_collect_on_ready to true (automatic collection on ready)

Step 3: Configure Breakage Conditions

Property Description Recommended Value
break_relative_speed Breaks if relative speed exceeds this value 0.0 (disabled) or 500.0
break_angle_degrees Breaks after this angle is held for a certain time 0.0 (disabled) or 80.0
break_angle_duration_sec Breaks if angle exceeds this for this many seconds 0.5
break_stretch_ratio Breaks if stretch ratio relative to initial distance exceeds this value 0.0 (disabled) or 1.5
use_break_delay_frames Treat BreakDelay in frames true
break_delay_frames Breaks if exceeded continuously for this many frames 1 to 10

5-2. Individual Settings (JointBreakParams)

Step 1: Create JointBreakParams Resource

  1. Right-click in the Project panel → New Resource
  2. Select JointBreakParams
  3. Save with a name (e.g., joint_params_weak.tres)

Step 2: Fill in Individual Settings

  1. Set joint_path to the NodePath of the target joint (e.g., ../ChainRoot/RigidBody2D2/GrooveJoint2D)
  2. Set individual break parameters:
    • -1.0 uses global settings
    • 0.0 or above uses individual settings

Step 3: Add to BreakableJointMonitor2D

  1. Add the created resource to the joint_params of BreakableJointMonitor2D

Example

BreakableJointMonitor2D
├── search_root: ../ChainRoot
├── break_angle_degrees: 80.0 (global setting)
└── joint_params:
    └── JointBreakParams
        ├── joint_path: ../ChainRoot/RigidBody2D2/GrooveJoint2D
        └── groove_break_angle_degrees: 90.0 (individual setting, more sensitive)

6. Common Setup Patterns

Pattern 1: Loose Rope

GrooveJoint2D Settings

  • bias: 0.2 (loose)
  • length: 8.0
  • initial_offset: 2.0

RigidBody2D Settings

  • linear_damp: 10.0 (strong damping)
  • angular_damp: 10.0

BreakableJointMonitor2D Settings

  • break_angle_degrees: 80.0
  • break_angle_duration_sec: 0.3 (cuts off quickly)

Use Case: Soft, swaying rope; breaks relatively easily

Pattern 2: Stiff Chain

GrooveJoint2D Settings

  • bias: 0.9 (stiff)
  • length: 8.0
  • initial_offset: 1.0

RigidBody2D Settings

  • mass: 3.0 (normal link)
  • mass: 8.0 (heavy parts, e.g., ball or weight)

BreakableJointMonitor2D Settings

  • break_angle_degrees: 0.0 (disabled, does not break)
  • Or use individual settings to allow breaking only specific parts

Use Case: Stiff chain; rarely breaks; hangs heavy objects

Pattern 3: Fixed Chain

Fixing the Head

  • Place a StaticBody2D
  • Connect to the first RigidBody2D with GrooveJoint2D

Fixing the Tail

  • Place a StaticBody2D
  • Connect to the last RigidBody2D with GrooveJoint2D

Use Case: Bridge chains, fixed ropes

Pattern 4: Branching Chain

Structure

  • Connect multiple chains with a single RigidBody2D
  • Place multiple GrooveJoint2Ds on the RigidBody2D at the connection point

Example

Chain1
└── RigidBody2D6
    └── GrooveJoint2D (within Chain1)
    └── GrooveJoint2D2 (connected to Chain2/RigidBody2D7)

Use Case: Connecting multiple chains, Y-shaped ropes

7. Troubleshooting

Problem 1: Chain does not move

Cause and Solution

Cause Solution
RigidBody2D is freeze=true Set freeze=false
RigidBody2D mass is 0 Set mass to 1.0 or higher
GrooveJoint2D node_a is incorrect Check NodePath, fix relative path
GrooveJoint2D node_b is incorrect Set node_b to ..

Problem 2: Chain breaks too easily

Cause and Solution

Cause Solution
break_angle_degrees is too small Increase the value (e.g., 80.0 → 120.0)
break_delay_frames is too small Increase the value (e.g., 1 → 10)
break_relative_speed is too small Increase the value, or set to 0.0 (disabled)
bias is too small (too loose) Increase the value (e.g., 0.2 → 0.9)

Problem 3: Chain does not break

Cause and Solution

Cause Solution
All breakage conditions are 0.0 (disabled) Set break_angle_degrees etc. to valid values
BreakableJointMonitor2D search_root is incorrect Set the correct NodePath
Joint is included in exclude_groups Check exclude_groups
auto_collect_on_ready=false Set to true, or call collect_joints() manually

Problem 4: Path is not displayed

Cause and Solution

Cause Solution
ChainPathBinder2D auto_update=false Set to true
output_paths is empty Add Path2D, or wait for automatic generation
search_root is incorrect Set the correct NodePath
seg nodes do not exist Set auto_create_seg_nodes=true, or manually create seg nodes
auto_detect_mode=false and chain_parts is empty Set auto_detect_mode=true, or add ChainPartResource to chain_parts

Problem 5: Setup tool does not work

Cause and Solution

Cause Solution
Fewer than two RigidBody2Ds under target_parent Place two or more RigidBody2Ds
target_parent is not set and there is no parent node Explicitly set target_parent
Not running in the editor Check _setup_button in the editor
Existing Joints have not been deleted Manually delete existing Joints before re-running

Problem 6: Chain is too heavy (performance issues)

Cause and Solution

Cause Solution
Too many RigidBody2Ds Reduce the number of links
continuous_cd is too large Set continuous_cd to 0 or 1
PathRibbonMesh2D update is heavy Set auto_update=false for manual updates, or reduce update frequency
BreakableJointMonitor2D is re-collecting every frame Set recollect_every_frame=false

8. Setup Checklist

Basic Chain

  • Place Node2D as root
  • Place two or more RigidBody2Ds
  • Add CollisionShape2D to each RigidBody2D
  • Add seg1 and seg2 nodes to each RigidBody2D
  • Add GrooveJoint2D to RigidBody2Ds starting from the second one
  • Correctly set node_a and node_b for each GrooveJoint2D

Visualization System

  • Place ChainPathBinder2D
  • Set auto_detect_mode=true
  • Set search_root
  • Create Path2D (or wait for automatic generation)
  • Place PathRibbonMesh2D
  • Set path_nodes to Path2D
  • Set texture

Joint Monitoring

  • Place BreakableJointMonitor2D
  • Set search_root
  • Set breakage conditions (e.g., break_angle_degrees)
  • Set auto_collect_on_ready=true

Automatic Setup (Using ChainJointSetupTool)

  • Place ChainJointSetupTool
  • Set target_parent
  • Set auto_setup_all=true
  • Check _setup_button or call setup_chain()

9. Example: Creating a Loose Rope

Step 1: Create Root Node

  1. Place an appropriate root node in the scene (e.g., Area2D, Node2D, etc.)
  2. Place a Node2D for the chain as its child

Step 2: Place RigidBody2D

  1. Place the required number of RigidBody2Ds as children of the chain Node2D

  2. Set the position of each RigidBody2D:

    • If arranging vertically: place them at appropriate intervals according to the length of each link
    • If arranging horizontally: adjust position.x
    • The interval between links is determined by the size of each link and the connection method

  3. Configure each RigidBody2D:

    • linear_damp: 10.0 (strong damping)
    • angular_damp: 10.0

Step 3: CollisionShape2D and seg Nodes

  1. Add CollisionShape2D to each RigidBody2D
  2. Choose the shape according to use case (RectangleShape2D, CapsuleShape2D, etc.)
  3. Add seg1 (position: 0, -10) and seg2 (position: 0, 10) to each RigidBody2D

Step 4: Place GrooveJoint2D

  1. Add a GrooveJoint2D as a child of each RigidBody2D starting from the second one:
    • position: (0, -16) (near the top edge of RigidBody2D)
    • node_a: Relative path to the previous RigidBody2D
    • node_b: .. (its own RigidBody2D)
    • bias: 0.2 (loose connection)
    • length: 8.0
    • initial_offset: 2.0

Step 5: StaticBody2D for Fixing (Optional)

  1. To fix the head: Place a StaticBody2D as a child of the root node

  2. Add a GrooveJoint2D as its child:

    • node_a: .. (the StaticBody2D itself)
    • node_b: Relative path to the first RigidBody2D
    • bias: 0.2
    • length: 8.0
    • initial_offset: 2.0

  3. Similarly configure for fixing the tail

Step 6: Visualization System

  1. Place a Path2D as a child of the root node

  2. Place a Node as a child of the root node and attach chain_path_binder.gd:

    • auto_detect_mode: true
    • search_root: Relative path to the chain Node2D
    • output_paths: Relative path to Path2D
    • enable_smooth_handles: true
    • smooth_handle_strength_px: 2.0

  3. Place a Node2D as a child of the root node and attach path_ribbon_mesh_2d.gd:

    • path_nodes: Relative path to Path2D
    • width: 20.0
    • ribbon_texture: Set an appropriate texture

Step 7: Joint Monitoring

  1. Place a Node as a child of the root node and attach breakable_joint_monitor_2d.gd:

    • search_root: Relative path to the chain Node2D
    • break_angle_degrees: 80.0
    • break_angle_duration_sec: 0.3
    • use_break_delay_frames: false
    • break_delay_frames: 3

  2. Set this in ChainPathBinder2D’s joint_monitor (optional)

10. Example: Creating a Stiff Chain with Weights

Step 1: Create Chain

  1. Place an appropriate root node in the scene
  2. Place a Node2D for the chain as its child

Step 2: Place RigidBody2D

  1. Place the required number of RigidBody2Ds as children of the chain Node2D

  2. Set the position of each RigidBody2D:

    • If arranging vertically: place them at appropriate intervals according to the length of each link
    • The first RigidBody2D can be set to freeze: true (fixed)

  3. Set a large mass for the RigidBody2D that acts as a weight (e.g., mass: 8.0)

  4. Add seg1 and seg2 to each RigidBody2D

Step 3: Place GrooveJoint2D

  1. Add a GrooveJoint2D as a child of each RigidBody2D starting from the second one:
    • position: (0, -16)
    • node_a: Relative path to the previous RigidBody2D
    • node_b: ..
    • bias: 0.9 (stiff connection)
    • length: 8.0
    • initial_offset: 1.0

Step 4: Visualization System

  1. Place a Path2D as a child of the chain Node2D
  2. Place a Node as a child of the chain Node2D and attach chain_path_binder.gd
  3. Place a Node2D as a child of the chain Node2D and attach path_ribbon_mesh_2d.gd (set an appropriate texture)

Step 5: Joint Monitoring (with Individual Settings)

  1. Place a Node as a child of the chain Node2D and attach breakable_joint_monitor_2d.gd
  2. Create a JointBreakParams resource as needed:
    • joint_path: Relative path to the target joint
    • groove_break_angle_degrees: 90.0 (individual setting)
    • groove_break_angle_duration_sec: 0.5
  3. Add it to joint_params of BreakableJointMonitor2D

Step 6: Create Branching Chain (Optional)

  1. Place another chain Node2D
  2. Place the required number of RigidBody2Ds similarly
  3. Add two GrooveJoint2Ds to the RigidBody2D at the connection point:
    • First one: Connection within its own chain
    • Second one: Connect to the RigidBody2D of the other chain

This concludes the chain setup guide.

1 Like