docs: Added RevoluteJoint documentation (#2451)

Added RevoluteJoint documentation section
Moved the related example to the joints subfolder, and renamed the second example to avoid confusion.

doc/bridge_packages/flame_forge2d/joints.md

@@ -25,7 +25,7 @@ Currently, Forge2D supports the following joints:
 - [`MouseJoint`](#mousejoint)
 - PrismaticJoint
 - [`PulleyJoint`](#pulleyjoint)
-- RevoluteJoint
+- [`RevoluteJoint`](#revolutejoint)
 - RopeJoint
 - WeldJoint
 - WheelJoint
@@ -338,3 +338,82 @@ joint.getCurrentLengthB()
 combined with prismatic joints. You should also cover the the anchor points 
 with static shapes to prevent one side from going to zero length.
 ```
+
+
+### `RevoluteJoint`
+
+A `RevoluteJoint` forces two bodies to share a common anchor point, often called a hinge point.
+The revolute joint has a single degree of freedom: the relative rotation of the two bodies.
+
+To create a `RevoluteJoint`, provide two bodies and a common point to the `initialize` method.
+The definition uses local anchor points so that the initial configuration can violate the
+constraint slightly.
+
+```dart
+final jointDef = RevoluteJointDef()
+  ..initialize(firstBody, secondBody, firstBody.position);
+world.createJoint(RevoluteJoint(jointDef));
+```
+
+```{flutter-app}
+:sources: ../../examples
+:page: revolute_joint
+:subfolder: stories/bridge_libraries/forge2d/joints
+:show: code popup
+```
+
+In some cases you might wish to control the joint angle. For this, the `RevoluteJointDef` has
+optional parameters that allow you to simulate a joint limit and/or a motor.
+
+
+#### Joint Limit
+
+You can limit the relative rotation with a joint limit that specifies a lower and upper angle.
+
+```dart
+jointDef
+  ..enableLimit = true
+  ..lowerAngle = 0
+  ..upperAngle = pi / 2;
+```
+
+- `enableLimit`: Set to true to enable angle limits
+- `lowerAngle`: The lower angle in radians
+- `upperAngle`: The upper angle in radians
+
+You change the limits after the joint was created with this method:
+
+```dart
+revoluteJoint.setLimits(0, pi);
+```
+
+
+#### Joint Motor
+
+You can use a motor to drive the relative rotation about the shared point. A maximum motor torque is
+provided so that infinite forces are not generated.
+
+```dart
+jointDef
+  ..enableMotor = true
+  ..motorSpeed = 5
+  ..maxMotorTorque = 100;
+```
+
+- `enableMotor`: Set to true to enable the motor
+- `motorSpeed`: The desired motor speed in radians per second
+- `maxMotorTorque`: The maximum motor torque used to achieve the desired motor speed in N-m.
+
+You change the motor's speed and torque after the joint was created using these methods:
+
+```dart
+revoluteJoint.setMotorSpeed(2);
+revoluteJoint.setMaxMotorTorque(200);
+```
+
+Also, you can get the joint angle and speed using the following methods:
+
+```dart
+revoluteJoint.jointAngle();
+revoluteJoint.jointSpeed();
+```

examples/lib/main.dart

@@ -12,6 +12,7 @@ import 'package:examples/stories/bridge_libraries/forge2d/joints/friction_joint.
 import 'package:examples/stories/bridge_libraries/forge2d/joints/motor_joint.dart';
 import 'package:examples/stories/bridge_libraries/forge2d/joints/mouse_joint.dart';
 import 'package:examples/stories/bridge_libraries/forge2d/joints/pulley_joint.dart';
+import 'package:examples/stories/bridge_libraries/forge2d/joints/revolute_joint.dart';
 import 'package:examples/stories/camera_and_viewport/camera_and_viewport.dart';
 import 'package:examples/stories/collision_detection/collision_detection.dart';
 import 'package:examples/stories/components/components.dart';
@@ -42,6 +43,7 @@ void main() {
     'motor_joint': MotorJointExample.new,
     'mouse_joint': MouseJointExample.new,
     'pulley_joint': PulleyJointExample.new,
+    'revolute_joint': RevoluteJointExample.new,
   };
   final game = routes[page]?.call();
   if (game != null) {

examples/lib/stories/bridge_libraries/forge2d/flame_forge2d.dart

@@ -7,15 +7,15 @@ import 'package:examples/stories/bridge_libraries/forge2d/composition_example.da
 import 'package:examples/stories/bridge_libraries/forge2d/contact_callbacks_example.dart';
 import 'package:examples/stories/bridge_libraries/forge2d/domino_example.dart';
 import 'package:examples/stories/bridge_libraries/forge2d/draggable_example.dart';
-import 'package:examples/stories/bridge_libraries/forge2d/joint_example.dart';
 import 'package:examples/stories/bridge_libraries/forge2d/joints/constant_volume_joint.dart';
 import 'package:examples/stories/bridge_libraries/forge2d/joints/distance_joint.dart';
 import 'package:examples/stories/bridge_libraries/forge2d/joints/friction_joint.dart';
 import 'package:examples/stories/bridge_libraries/forge2d/joints/motor_joint.dart';
 import 'package:examples/stories/bridge_libraries/forge2d/joints/mouse_joint.dart';
 import 'package:examples/stories/bridge_libraries/forge2d/joints/pulley_joint.dart';
+import 'package:examples/stories/bridge_libraries/forge2d/joints/revolute_joint.dart';
 import 'package:examples/stories/bridge_libraries/forge2d/raycast_example.dart';
-import 'package:examples/stories/bridge_libraries/forge2d/revolute_joint_example.dart';
+import 'package:examples/stories/bridge_libraries/forge2d/revolute_joint_with_motor_example.dart';
 import 'package:examples/stories/bridge_libraries/forge2d/sprite_body_example.dart';
 import 'package:examples/stories/bridge_libraries/forge2d/tappable_example.dart';
 import 'package:examples/stories/bridge_libraries/forge2d/widget_example.dart';
@@ -50,9 +50,10 @@ void addForge2DStories(Dashbook dashbook) {
       info: ContactCallbacksExample.description,
     )
     ..add(
-      'RevoluteJoint',
-      (DashbookContext ctx) => GameWidget(game: RevoluteJointExample()),
-      codeLink: link('revolute_joint_example.dart'),
+      'RevoluteJoint with Motor',
+      (DashbookContext ctx) =>
+          GameWidget(game: RevoluteJointWithMotorExample()),
+      codeLink: link('revolute_joint_with_motor_example.dart'),
       info: RevoluteJointExample.description,
     )
     ..add(
@@ -79,12 +80,6 @@ void addForge2DStories(Dashbook dashbook) {
       codeLink: link('draggable_example.dart'),
       info: DraggableExample.description,
     )
-    ..add(
-      'Basic joint',
-      (DashbookContext ctx) => GameWidget(game: JointExample()),
-      codeLink: link('joint_example.dart'),
-      info: JointExample.description,
-    )
     ..add(
       'Camera',
       (DashbookContext ctx) => GameWidget(game: CameraExample()),
@@ -144,5 +139,11 @@ void addJointsStories(Dashbook dashbook) {
         (DashbookContext ctx) => GameWidget(game: PulleyJointExample()),
         codeLink: link('joints/pulley_joint.dart'),
         info: PulleyJointExample.description,
+      )
+      .add(
+        'RevoluteJoint',
+        (DashbookContext ctx) => GameWidget(game: RevoluteJointExample()),
+        codeLink: link('revolute_joint.dart'),
+        info: RevoluteJointExample.description,
       );
 }

examples/lib/stories/bridge_libraries/forge2d/joints/mouse_joint.dart

@@ -1,4 +1,4 @@
-import 'package:examples/stories/bridge_libraries/forge2d/revolute_joint_example.dart';
+import 'package:examples/stories/bridge_libraries/forge2d/revolute_joint_with_motor_example.dart';
 import 'package:examples/stories/bridge_libraries/forge2d/utils/balls.dart';
 import 'package:examples/stories/bridge_libraries/forge2d/utils/boundaries.dart';
 import 'package:flame/input.dart';

examples/lib/stories/bridge_libraries/forge2d/joints/revolute_joint.dart

@@ -5,7 +5,7 @@ import 'package:examples/stories/bridge_libraries/forge2d/utils/boundaries.dart'
 import 'package:flame/input.dart';
 import 'package:flame_forge2d/flame_forge2d.dart';
 
-class JointExample extends Forge2DGame with TapDetector {
+class RevoluteJointExample extends Forge2DGame with TapDetector {
   static const description = '''
     In this example we use a joint to keep a body with several fixtures stuck
     to another body.
@@ -13,7 +13,7 @@ class JointExample extends Forge2DGame with TapDetector {
     Tap the screen to add more of these combined bodies.
   ''';
 
-  JointExample() : super(gravity: Vector2(0, 10.0));
+  RevoluteJointExample() : super(gravity: Vector2(0, 10.0));
 
   @override
   Future<void> onLoad() async {

examples/lib/stories/bridge_libraries/forge2d/revolute_joint_with_motor_example.dart

@@ -5,7 +5,7 @@ import 'package:examples/stories/bridge_libraries/forge2d/utils/boundaries.dart'
 import 'package:flame/input.dart';
 import 'package:flame_forge2d/flame_forge2d.dart';
 
-class RevoluteJointExample extends Forge2DGame with TapDetector {
+class RevoluteJointWithMotorExample extends Forge2DGame with TapDetector {
   static const String description = '''
     This example showcases a revolute joint, which is the spinning balls in the
     center.