Added comments, screenshot and documentation for the hinge joint example.

examples/_main/loader.go

@@ -733,7 +733,7 @@ embedded_components {
 embedded_components {
   id: "physics/joint"
   type: "collectionproxy"
-  data: "collection: \"/examples/physics/joint/joint.collection\"\n"
+  data: "collection: \"/examples/physics/hinge_joint/hinge_joint.collection\"\n"
   "exclude: false\n"
   ""
   position {

examples/physics/joint/joint.collection → examples/physics/hinge_joint/hinge_joint.collection

@@ -9,7 +9,7 @@ embedded_instances {
   "type: COLLISION_OBJECT_TYPE_DYNAMIC\\n"
   "mass: 5.0\\n"
   "friction: 0.9\\n"
-  "restitution: 0.01\\n"
+  "restitution: 0.1\\n"
   "group: \\\"default\\\"\\n"
   "mask: \\\"default\\\"\\n"
   "embedded_collision_shape {\\n"
@@ -31,8 +31,8 @@ embedded_instances {
   "  }\\n"
   "  data: 35.0\\n"
   "}\\n"
-  "linear_damping: 0.1\\n"
-  "angular_damping: 0.1\\n"
+  "linear_damping: 0.0\\n"
+  "angular_damping: 0.0\\n"
   "locked_rotation: false\\n"
   "bullet: false\\n"
   "\"\n"
@@ -193,6 +193,60 @@ embedded_instances {
   "    w: 1.0\n"
   "  }\n"
   "}\n"
+  "embedded_components {\n"
+  "  id: \"label\"\n"
+  "  type: \"label\"\n"
+  "  data: \"size {\\n"
+  "  x: 128.0\\n"
+  "  y: 32.0\\n"
+  "  z: 0.0\\n"
+  "  w: 0.0\\n"
+  "}\\n"
+  "scale {\\n"
+  "  x: 0.5\\n"
+  "  y: 0.5\\n"
+  "  z: 1.0\\n"
+  "  w: 0.0\\n"
+  "}\\n"
+  "color {\\n"
+  "  x: 0.0\\n"
+  "  y: 0.5647059\\n"
+  "  z: 0.99215686\\n"
+  "  w: 1.0\\n"
+  "}\\n"
+  "outline {\\n"
+  "  x: 1.0\\n"
+  "  y: 1.0\\n"
+  "  z: 1.0\\n"
+  "  w: 1.0\\n"
+  "}\\n"
+  "shadow {\\n"
+  "  x: 1.0\\n"
+  "  y: 1.0\\n"
+  "  z: 1.0\\n"
+  "  w: 1.0\\n"
+  "}\\n"
+  "leading: 1.0\\n"
+  "tracking: 0.0\\n"
+  "pivot: PIVOT_CENTER\\n"
+  "blend_mode: BLEND_MODE_ALPHA\\n"
+  "line_break: false\\n"
+  "text: \\\"Click or touch to change direction\\\"\\n"
+  "font: \\\"/assets/text48.font\\\"\\n"
+  "material: \\\"/builtins/fonts/label.material\\\"\\n"
+  "\"\n"
+  "  position {\n"
+  "    x: 360.0\n"
+  "    y: 360.0\n"
+  "    z: 0.0\n"
+  "  }\n"
+  "  rotation {\n"
+  "    x: 0.0\n"
+  "    y: 0.0\n"
+  "    z: 0.0\n"
+  "    w: 1.0\n"
+  "  }\n"
+  "}\n"
   ""
   position {
     x: 0.0
@@ -215,7 +269,7 @@ embedded_instances {
   id: "body"
   data: "components {\n"
   "  id: \"script\"\n"
-  "  component: \"/examples/physics/joint/joint.script\"\n"
+  "  component: \"/examples/physics/hinge_joint/hinge_joint.script\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"
@@ -255,7 +309,7 @@ embedded_instances {
   "type: COLLISION_OBJECT_TYPE_DYNAMIC\\n"
   "mass: 20.0\\n"
   "friction: 0.1\\n"
-  "restitution: 0.01\\n"
+  "restitution: 0.1\\n"
   "group: \\\"default\\\"\\n"
   "mask: \\\"default\\\"\\n"
   "embedded_collision_shape {\\n"
@@ -296,60 +350,6 @@ embedded_instances {
   "    w: 1.0\n"
   "  }\n"
   "}\n"
-  "embedded_components {\n"
-  "  id: \"label\"\n"
-  "  type: \"label\"\n"
-  "  data: \"size {\\n"
-  "  x: 128.0\\n"
-  "  y: 32.0\\n"
-  "  z: 0.0\\n"
-  "  w: 0.0\\n"
-  "}\\n"
-  "scale {\\n"
-  "  x: 0.5\\n"
-  "  y: 0.5\\n"
-  "  z: 1.0\\n"
-  "  w: 0.0\\n"
-  "}\\n"
-  "color {\\n"
-  "  x: 0.0\\n"
-  "  y: 0.5647059\\n"
-  "  z: 0.99215686\\n"
-  "  w: 1.0\\n"
-  "}\\n"
-  "outline {\\n"
-  "  x: 1.0\\n"
-  "  y: 1.0\\n"
-  "  z: 1.0\\n"
-  "  w: 1.0\\n"
-  "}\\n"
-  "shadow {\\n"
-  "  x: 1.0\\n"
-  "  y: 1.0\\n"
-  "  z: 1.0\\n"
-  "  w: 1.0\\n"
-  "}\\n"
-  "leading: 1.0\\n"
-  "tracking: 0.0\\n"
-  "pivot: PIVOT_CENTER\\n"
-  "blend_mode: BLEND_MODE_ALPHA\\n"
-  "line_break: false\\n"
-  "text: \\\"Going forward\\\"\\n"
-  "font: \\\"/assets/text48.font\\\"\\n"
-  "material: \\\"/builtins/fonts/label.material\\\"\\n"
-  "\"\n"
-  "  position {\n"
-  "    x: 16.24\n"
-  "    y: 91.362\n"
-  "    z: 0.0\n"
-  "  }\n"
-  "  rotation {\n"
-  "    x: 0.0\n"
-  "    y: 0.0\n"
-  "    z: 0.0\n"
-  "    w: 1.0\n"
-  "  }\n"
-  "}\n"
   ""
   position {
     x: 360.0
@@ -377,7 +377,7 @@ embedded_instances {
   "type: COLLISION_OBJECT_TYPE_DYNAMIC\\n"
   "mass: 5.0\\n"
   "friction: 0.9\\n"
-  "restitution: 0.01\\n"
+  "restitution: 0.1\\n"
   "group: \\\"default\\\"\\n"
   "mask: \\\"default\\\"\\n"
   "embedded_collision_shape {\\n"
@@ -399,8 +399,8 @@ embedded_instances {
   "  }\\n"
   "  data: 35.0\\n"
   "}\\n"
-  "linear_damping: 0.1\\n"
-  "angular_damping: 0.1\\n"
+  "linear_damping: 0.0\\n"
+  "angular_damping: 0.0\\n"
   "locked_rotation: false\\n"
   "bullet: false\\n"
   "\"\n"

examples/physics/hinge_joint/hinge_joint.md

@@ -0,0 +1,28 @@
+---
+title: Joint physics
+brief: This example shows a simple setup with a dynamic body physics object and two dynamic wheel physics object joined together with a joint of type "hinge". The hinge joint can simulate an axle or a pin on which other object is rotating in respect to the base. The example shows how to create, destroy and change properties of the joints.
+scripts: hinge_joint.script
+---
+
+![hinge_joint](hinge_joint.png)
+
+The setup consists of four game objects. The *game.project* physics *GravityY* property is set to -500 to match the scale of the setup.
+
+body
+: The square stone block. Contains:
+  - A *Sprite* component with the stone block image.
+  - A *Collision object* component. The *Type* is set to `DYNAMIC`. A box *Shape* matching the sprite image is added to the components.
+  - A script that joines the wheel game objects to to the body and reacts to user input by changing the direction of the rotation of the hinge joints.
+  - A label with an instruction to the user.
+
+frontwheel
+: The cirular metal wheel. Contains:
+  - A *Sprite* component with the metal circle image.
+  - A *Collision object* component. Also has *Type* set to `DYNAMIC`, *Friction* set to 0.9 and *Restitution* to 0.1. A box *Shape* matching the sprite image is added to the components.
+
+backwheel
+: The same as above.
+
+walls
+: The outer walls. Contains:
+  - A *Collision object* component. The *Type* is set to `STATIC`. 4 box *Shapes* are added to the component. These are placed just outside of the game view.

examples/physics/hinge_joint/hinge_joint.script

@@ -0,0 +1,46 @@
+local frontwheel = "frontwheel#collisionobject" -- <1>
+local backwheel = "backwheel#collisionobject"
+local body = "body#collisionobject"
+
+local center_anchor = vmath.vector3(0, 0, 0)
+local frontwheel_anchor = vmath.vector3(60, -60, 0)
+local backwheel_anchor = vmath.vector3(-60, -60, 0)
+
+local hinge_props = { enable_motor = true, enable_limit = false, max_motor_torque = 60, motor_speed = 5 * 2 * math.pi}
+
+function init(self)
+	msg.post(".", "acquire_input_focus") -- <2>
+	self.forward = true -- <3>
+	physics.create_joint(physics.JOINT_TYPE_HINGE, frontwheel, "frontwheel", center_anchor, body, frontwheel_anchor, hinge_props) -- <4>
+	physics.create_joint(physics.JOINT_TYPE_HINGE, backwheel, "backwheel", center_anchor, body, backwheel_anchor, hinge_props)
+end
+
+function on_input(self, action_id, action)
+	if action_id == hash("touch") and action.pressed then -- <5>
+		self.forward = not self.forward -- <6>
+		if self.forward then -- <7>
+			hinge_props.motor_speed = 5 * 2 * math.pi -- <8>
+		else  -- <9>
+			hinge_props.motor_speed = -5 * 2 * math.pi -- <10>
+		end
+		physics.destroy_joint(frontwheel, "frontwheel") -- <11>
+		physics.destroy_joint(backwheel, "backwheel")
+		physics.create_joint(physics.JOINT_TYPE_HINGE, frontwheel, "frontwheel", center_anchor, body, frontwheel_anchor, hinge_props) -- <12>
+		physics.create_joint(physics.JOINT_TYPE_HINGE, backwheel, "backwheel", center_anchor, body, backwheel_anchor, hinge_props)
+	end
+end
+
+--[[
+1. Store collision objects ids, vectors used for anchors and hinge properties used for creating joints in local variables.
+2. Tell the engine that this object ("." is shorthand for the current game object) should listen to input. Any input will be received in the `on_input()` function.
+3. Set a flag self.forward used to define the direction of the rotation of the joined wheels.
+4. Create a joint of type "hinge" (a revolute joint, a pin or an axle) between a center of frontwheel collision object and an anchor ((-60,-60) from the center) on body collision object with provided properties. Do the same for the second wheel.
+5. If we receive input (touch or mouse movement) we switch the direction of rotation of the wheels.
+6. Negate the current flag defining the direction.
+7. If the direction flag is true, we are going forward.
+8. Set the motor_speed property to 5 revolutions per second in clockwise direction.
+9. If the direction flag is false, we are going backward.
+10. Set the motor_speed property to 5 revolutions per second in counter-clockwise direction.
+11. Destroy a current joint for frontwheel and backwheel.
+12. Recreate the joints with new properties.
+--]]

examples/physics/joint/joint.md

@@ -1,24 +0,0 @@
----
-title: Kinematic physics
-brief: This example shows a simple setup with a kinematic physics objects. The difference between dynamic objects, simulated by the physics engine, and kinematic objects, that are user controlled, is clearly seen here.
-scripts: kinematic.script
----
-
-![kinematic](kinematic.png)
-
-The setup consists of three game objects. The *game.project* physics *GravityY* property is set to -500 to match the scale of the setup.
-
-block
-: The square stone block. Contains:
-  - A *Sprite* component with the stone block image.
-  - A *Collision object* component. The *Type* is set to `KINEMATIC`. A box *Shape* matching the sprite image is added to the components.
-  - A script that moves the game object to where the user clicks.
-
-block2
-: The rectangular stone block. Contains:
-  - A *Sprite* component with the stone block image.
-  - A *Collision object* component. Also has *Type* set to `DYNAMIC`, *Friction* set to 0 and *Restitution* to 1.0. A box *Shape* matching the sprite image is added to the components.
-
-walls
-: The outer walls. Contains:
-  - A *Collision object* component. The *Type* is set to `STATIC`. 4 box *Shapes* are added to the component. These are placed just outside of the game view.

examples/physics/joint/joint.script

@@ -1,37 +0,0 @@
-local frontwheel = "frontwheel#collisionobject"
-local backwheel = "backwheel#collisionobject"
-local body = "body#collisionobject"
-
-local center_anchor = vmath.vector3(0, 0, 0)
-local frontwheel_anchor = vmath.vector3(50, -60, 0)
-local backwheel_anchor = vmath.vector3(-50, -60, 0)
-
-local hinge_props = { enable_motor = true, enable_limit = false, max_motor_torque = 60, motor_speed = 50}
-
-function init(self)
-	msg.post(".", "acquire_input_focus") -- <1>
-	self.forward = true
-	physics.create_joint(physics.JOINT_TYPE_HINGE, frontwheel, "frontwheel", vmath.vector3(0, 0, 0), body, frontwheel_anchor, hinge_props)
-	physics.create_joint(physics.JOINT_TYPE_HINGE, backwheel, "backwheel", vmath.vector3(0, 0, 0), body, backwheel_anchor, hinge_props)
-end
-
-function on_input(self, action_id, action)
-	if action_id == hash("touch") and action.pressed then -- <3>
-		self.forward = not self.forward
-		if self.forward then -- <4>
-			hinge_props.motor_speed = 50
-			label.set_text("#label", "Going forward")-- <5>
-		else
-			hinge_props.motor_speed = -50
-			label.set_text("#label", "Going backward")-- <5>
-		end
-		physics.destroy_joint(frontwheel, "frontwheel")
-		physics.destroy_joint(backwheel, "backwheel")
-		physics.create_joint(physics.JOINT_TYPE_HINGE, frontwheel, "frontwheel", vmath.vector3(0, 0, 0), body, frontwheel_anchor, hinge_props)
-		physics.create_joint(physics.JOINT_TYPE_HINGE, backwheel, "backwheel", vmath.vector3(0, 0, 0), body, backwheel_anchor, hinge_props)
-	end
-end
-
---[[
-1. TODO
---]]