Sound Panning Example

Completed sound panning example ready for pull request.

assets/sprites.atlas

@@ -247,6 +247,33 @@ animations {
   flip_horizontal: 0
   flip_vertical: 0
 }
+animations {
+  id: "coin"
+  images {
+    image: "/assets/images/coin/dcoin_1.png"
+    sprite_trim_mode: SPRITE_TRIM_MODE_OFF
+  }
+  images {
+    image: "/assets/images/coin/dcoin_2.png"
+    sprite_trim_mode: SPRITE_TRIM_MODE_OFF
+  }
+  images {
+    image: "/assets/images/coin/dcoin_3.png"
+    sprite_trim_mode: SPRITE_TRIM_MODE_OFF
+  }
+  images {
+    image: "/assets/images/coin/dcoin_4.png"
+    sprite_trim_mode: SPRITE_TRIM_MODE_OFF
+  }
+  images {
+    image: "/assets/images/coin/dcoin_5.png"
+    sprite_trim_mode: SPRITE_TRIM_MODE_OFF
+  }
+  playback: PLAYBACK_LOOP_FORWARD
+  fps: 8
+  flip_horizontal: 0
+  flip_vertical: 0
+}
 margin: 0
 extrude_borders: 2
 inner_padding: 0

examples/_main/loader.go

@@ -748,3 +748,21 @@ embedded_components {
     w: 1.0
   }
 }
+embedded_components {
+  id: "sound/panning"
+  type: "collectionproxy"
+  data: "collection: \"/examples/sound/panning/panning.collection\"\n"
+  "exclude: false\n"
+  ""
+  position {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+  }
+  rotation {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+}

examples/_main/menu.gui_script

@@ -107,7 +107,7 @@ function init(self)
 	self.index["gui"] = { "button", "stencil", "load_texture", "pointer_over", "color"}
 	self.index["input"] = { "move", "text", "down_duration", "mouse_and_touch" }
 	self.index["particles"] = { "particlefx", "modifiers" }
-	self.index["sound"] = { "music", "fade_in_out" }
+	self.index["sound"] = { "music", "fade_in_out", "panning" }
 	self.index["render"] = { "camera" }
 	self.index["debug"] = { "physics", "profile" }
 	self.index["collection"] = { "proxy", "splash" }

examples/sound/panning/pan.script

@@ -0,0 +1,41 @@
+local position_min = 0  -- <1>
+local position_max = window.get_size(width)  -- <2>
+
+local function normalize_position(x_position)  -- <3>
+	local average = (position_min + position_max) / 2;
+	local range = (position_max - position_min) / 1.8;
+	local result = (x_position - average) / range;
+	return result;
+end
+
+function init(self)  -- <4>
+	physics.set_gravity(vmath.vector3(0, 0, 0))
+	msg.post("pan:/coin#collision", "apply_force", {force = vmath.vector3(1200, 1300, 0), position = go.get_world_position()})
+end
+
+function on_message(self, message_id, message, sender)  -- <5>
+	if message_id == hash("collision_response") then
+		local coin_pos = normalize_position(go.get_position("pan:/coin").x)
+		sound.play("pan:/coin#coin", { gain = 0.6, pan = coin_pos } )
+	end
+end
+
+--[[
+
+	1. - Local variable to represent the minimum x position value. 
+
+	2. - Local variable to represent the maximum x position value. window.get_size(width) to get screen width used for maximum x position value.
+
+	3. - This function uses the screen x position min & max local variables that is set at the top of the script to get an average and range then 
+		pass in the coin objects x position into result to get a normalized value and the function returns that value. note: in range if we divide by 2.0
+		we would get range -1.0 to 1.0 full 45 degree pan at min/max positions, instead use 1.8 to get around a 40 deg pan that way we always get a little
+		bit of sound in both left and right channel outputs no matter the min/max position.
+
+	4. - In the initialize function we set gravity to 0 and apply some force to the dynamic coin object giving it movement.
+
+	5. - When a collision_response is received we pass in the coin objects x position into the normalize_position function and set the results to the local variable 
+		coin_pos. Then play a sound and pass in coin_pos into the sounds pan property.
+
+	Now we have simple sound localization using the pan property. If you close your eyes, you should be able to gauge which direction the collisions are occurring.(as long as you are using stereo sound) 
+
+--]]

examples/sound/panning/panning.collection

@@ -0,0 +1,251 @@
+name: "pan"
+scale_along_z: 0
+embedded_instances {
+  id: "walls"
+  data: "embedded_components {\n"
+  "  id: \"collisionobject\"\n"
+  "  type: \"collisionobject\"\n"
+  "  data: \"collision_shape: \\\"\\\"\\n"
+  "type: COLLISION_OBJECT_TYPE_STATIC\\n"
+  "mass: 0.0\\n"
+  "friction: 0.9\\n"
+  "restitution: 0.1\\n"
+  "group: \\\"wall\\\"\\n"
+  "mask: \\\"coin\\\"\\n"
+  "embedded_collision_shape {\\n"
+  "  shapes {\\n"
+  "    shape_type: TYPE_BOX\\n"
+  "    position {\\n"
+  "      x: -50.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"
+  "    index: 0\\n"
+  "    count: 3\\n"
+  "  }\\n"
+  "  shapes {\\n"
+  "    shape_type: TYPE_BOX\\n"
+  "    position {\\n"
+  "      x: 770.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"
+  "    index: 3\\n"
+  "    count: 3\\n"
+  "  }\\n"
+  "  shapes {\\n"
+  "    shape_type: TYPE_BOX\\n"
+  "    position {\\n"
+  "      x: 360.0\\n"
+  "      y: 770.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"
+  "    index: 6\\n"
+  "    count: 3\\n"
+  "  }\\n"
+  "  shapes {\\n"
+  "    shape_type: TYPE_BOX\\n"
+  "    position {\\n"
+  "      x: 360.0\\n"
+  "      y: -50.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"
+  "    index: 9\\n"
+  "    count: 3\\n"
+  "  }\\n"
+  "  data: 50.0\\n"
+  "  data: 360.0\\n"
+  "  data: 10.0\\n"
+  "  data: 50.0\\n"
+  "  data: 360.0\\n"
+  "  data: 10.0\\n"
+  "  data: 460.0\\n"
+  "  data: 50.0\\n"
+  "  data: 10.0\\n"
+  "  data: 460.0\\n"
+  "  data: 50.0\\n"
+  "  data: 10.0\\n"
+  "}\\n"
+  "linear_damping: 0.0\\n"
+  "angular_damping: 0.0\\n"
+  "locked_rotation: false\\n"
+  "bullet: false\\n"
+  "\"\n"
+  "  position {\n"
+  "    x: 0.0\n"
+  "    y: 0.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
+    y: 0.0
+    z: 0.0
+  }
+  rotation {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  scale3 {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+  }
+}
+embedded_instances {
+  id: "coin"
+  data: "components {\n"
+  "  id: \"pan\"\n"
+  "  component: \"/examples/sound/panning/pan.script\"\n"
+  "  position {\n"
+  "    x: 0.0\n"
+  "    y: 0.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"
+  "embedded_components {\n"
+  "  id: \"collision\"\n"
+  "  type: \"collisionobject\"\n"
+  "  data: \"collision_shape: \\\"\\\"\\n"
+  "type: COLLISION_OBJECT_TYPE_DYNAMIC\\n"
+  "mass: 0.09\\n"
+  "friction: 0.0\\n"
+  "restitution: 1.0\\n"
+  "group: \\\"coin\\\"\\n"
+  "mask: \\\"wall\\\"\\n"
+  "embedded_collision_shape {\\n"
+  "  shapes {\\n"
+  "    shape_type: TYPE_SPHERE\\n"
+  "    position {\\n"
+  "      x: 0.0\\n"
+  "      y: 0.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"
+  "    index: 0\\n"
+  "    count: 1\\n"
+  "  }\\n"
+  "  data: 35.0\\n"
+  "}\\n"
+  "linear_damping: 0.0\\n"
+  "angular_damping: 0.0\\n"
+  "locked_rotation: false\\n"
+  "bullet: false\\n"
+  "\"\n"
+  "  position {\n"
+  "    x: 0.0\n"
+  "    y: 0.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"
+  "embedded_components {\n"
+  "  id: \"sprite\"\n"
+  "  type: \"sprite\"\n"
+  "  data: \"tile_set: \\\"/assets/sprites.atlas\\\"\\n"
+  "default_animation: \\\"coin\\\"\\n"
+  "material: \\\"/builtins/materials/sprite.material\\\"\\n"
+  "blend_mode: BLEND_MODE_ALPHA\\n"
+  "\"\n"
+  "  position {\n"
+  "    x: 0.0\n"
+  "    y: 0.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"
+  "embedded_components {\n"
+  "  id: \"coin\"\n"
+  "  type: \"sound\"\n"
+  "  data: \"sound: \\\"/examples/sound/panning/dcoin.ogg\\\"\\n"
+  "looping: 0\\n"
+  "group: \\\"master\\\"\\n"
+  "gain: 1.0\\n"
+  "pan: 0.0\\n"
+  "speed: 1.0\\n"
+  "loopcount: 0\\n"
+  "\"\n"
+  "  position {\n"
+  "    x: 0.0\n"
+  "    y: 0.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: 249.0
+    y: 398.0
+    z: 0.0
+  }
+  rotation {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  scale3 {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+  }
+}

examples/sound/panning/panning.md

@@ -0,0 +1,22 @@
+---
+title: Panning
+brief: This example demonstrates how to pan a sound effect according to a GO's(game object) position on the screen.
+scripts: pan.script
+---
+
+Overview : A coin bounces around the screen and on collision detection with the walls we get the coins x position then normalize that value for use in the sound components pan property. As the API states "The pan on the sound-component. The valid range is from -1.0 to 1.0, representing -45 degrees left, to +45 degrees right." we can use this information along with our x value from our coin object and normalize it into the correct range. 
+
+![panning](panning.png)
+
+The setup consists of a coin game object and walls for collision.
+
+Coin
+: contains:
+  - A *Sound* component.
+  - A *Collision* component. With *Type* set to `DYNAMIC` and a Sphere *Shape*.
+  - A script used to set initial coin movement then set pan value and play a sound on collision.
+  - A sprite component with default animation set as coin
+
+Walls
+: contains:
+  - A *Collision* component set to `STATIC` and 4 box *Shapes* that make up the walls along the bounds of the game screen.