From b83c50737cf7d1d86933ca0b882ede7928df68ac Mon Sep 17 00:00:00 2001 From: Eugene Kleshnin Date: Fri, 31 Mar 2023 20:23:31 +0100 Subject: [PATCH] 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 | 81 ++++++++++++++++++- examples/lib/main.dart | 2 + .../forge2d/flame_forge2d.dart | 23 +++--- .../forge2d/joints/mouse_joint.dart | 2 +- .../revolute_joint.dart} | 6 +- ...=> revolute_joint_with_motor_example.dart} | 2 +- 6 files changed, 99 insertions(+), 17 deletions(-) rename examples/lib/stories/bridge_libraries/forge2d/{joint_example.dart => joints/revolute_joint.dart} (92%) rename examples/lib/stories/bridge_libraries/forge2d/{revolute_joint_example.dart => revolute_joint_with_motor_example.dart} (97%) diff --git a/doc/bridge_packages/flame_forge2d/joints.md b/doc/bridge_packages/flame_forge2d/joints.md index dd5b798e8..8b23d58a4 100644 --- a/doc/bridge_packages/flame_forge2d/joints.md +++ b/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(); +``` diff --git a/examples/lib/main.dart b/examples/lib/main.dart index 5f39aa024..f8a67be2e 100644 --- a/examples/lib/main.dart +++ b/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) { diff --git a/examples/lib/stories/bridge_libraries/forge2d/flame_forge2d.dart b/examples/lib/stories/bridge_libraries/forge2d/flame_forge2d.dart index d9b3f0dc9..457e13933 100644 --- a/examples/lib/stories/bridge_libraries/forge2d/flame_forge2d.dart +++ b/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, ); } diff --git a/examples/lib/stories/bridge_libraries/forge2d/joints/mouse_joint.dart b/examples/lib/stories/bridge_libraries/forge2d/joints/mouse_joint.dart index b89b26187..ccb7f7976 100644 --- a/examples/lib/stories/bridge_libraries/forge2d/joints/mouse_joint.dart +++ b/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'; diff --git a/examples/lib/stories/bridge_libraries/forge2d/joint_example.dart b/examples/lib/stories/bridge_libraries/forge2d/joints/revolute_joint.dart similarity index 92% rename from examples/lib/stories/bridge_libraries/forge2d/joint_example.dart rename to examples/lib/stories/bridge_libraries/forge2d/joints/revolute_joint.dart index b9d0eadc6..e9c7fea26 100644 --- a/examples/lib/stories/bridge_libraries/forge2d/joint_example.dart +++ b/examples/lib/stories/bridge_libraries/forge2d/joints/revolute_joint.dart @@ -5,15 +5,15 @@ 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. - + 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 onLoad() async { diff --git a/examples/lib/stories/bridge_libraries/forge2d/revolute_joint_example.dart b/examples/lib/stories/bridge_libraries/forge2d/revolute_joint_with_motor_example.dart similarity index 97% rename from examples/lib/stories/bridge_libraries/forge2d/revolute_joint_example.dart rename to examples/lib/stories/bridge_libraries/forge2d/revolute_joint_with_motor_example.dart index 644812486..47cd8c63c 100644 --- a/examples/lib/stories/bridge_libraries/forge2d/revolute_joint_example.dart +++ b/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.