Add entity picking example (#90)

Author: aglitchman

input/entity_picking/all.texture_profiles

@@ -0,0 +1,18 @@
+path_settings {
+  path: "**"
+  profile: "Default"
+}
+profiles {
+  name: "Default"
+  platforms {
+    os: OS_ID_GENERIC
+    formats {
+      format: TEXTURE_FORMAT_RGBA
+      compression_level: BEST
+      compression_type: COMPRESSION_TYPE_DEFAULT
+    }
+    mipmaps: false
+    max_texture_size: 0
+    premultiply_alpha: true
+  }
+}

input/entity_picking/assets/materials/unlit.fp

@@ -0,0 +1,27 @@
+#version 140
+
+// Inputs should match the vertex shader's outputs.
+in vec2 var_texcoord0;
+
+// The texture to sample.
+uniform lowp sampler2D texture0;
+
+// The final color of the fragment.
+out lowp vec4 final_color;
+
+uniform fs_uniforms
+{
+    mediump vec4 tint;
+};
+
+void main()
+{
+    // Pre-multiply alpha since all runtime textures already are
+    vec4 tint_pm = vec4(tint.xyz * tint.w, tint.w);
+
+    // Sample the texture at the fragment's texture coordinates.
+    vec4 color = texture(texture0, var_texcoord0.xy) * tint_pm;
+
+    // Output the sampled color.
+    final_color = color;
+}

input/entity_picking/assets/materials/unlit.material

@@ -0,0 +1,31 @@
+name: "unlit"
+tags: "model"
+vertex_program: "/assets/materials/unlit.vp"
+fragment_program: "/assets/materials/unlit.fp"
+vertex_space: VERTEX_SPACE_LOCAL
+vertex_constants {
+  name: "mtx_view"
+  type: CONSTANT_TYPE_VIEW
+}
+vertex_constants {
+  name: "mtx_proj"
+  type: CONSTANT_TYPE_PROJECTION
+}
+fragment_constants {
+  name: "tint"
+  type: CONSTANT_TYPE_USER
+  value {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+}
+samplers {
+  name: "texture0"
+  wrap_u: WRAP_MODE_CLAMP_TO_EDGE
+  wrap_v: WRAP_MODE_CLAMP_TO_EDGE
+  filter_min: FILTER_MODE_MIN_LINEAR
+  filter_mag: FILTER_MODE_MAG_LINEAR
+  max_anisotropy: 0.0
+}

input/entity_picking/assets/materials/unlit.vp

@@ -0,0 +1,28 @@
+#version 140
+
+// The model's vertex position and texture coordinates.
+in vec4 position;
+in vec2 texcoord0;
+
+// The model's world matrix.
+in mat4 mtx_world;
+
+// The projection and view matrices.
+uniform general_vp
+{
+    mat4 mtx_view;
+    mat4 mtx_proj;
+};
+
+// The output of a vertex shader are passed to the fragment shader.
+// The texture coordinates of the vertex.
+out vec2 var_texcoord0;
+
+void main()
+{
+    // Pass the texture coordinates to the fragment shader.
+    var_texcoord0 = texcoord0;
+
+    // Transform the vertex position to clip space.
+    gl_Position = mtx_proj * mtx_view * mtx_world * vec4(position.xyz, 1.0);
+}

input/entity_picking/assets/models/kenney_prototype-kit/License.txt

@@ -0,0 +1,28 @@
+	
+
+	Prototype Kit (1.0)
+
+	Created/distributed by Kenney (www.kenney.nl)
+	Creation date: 28-08-2024 09:59
+	
+			------------------------------
+
+	License: (Creative Commons Zero, CC0)
+	http://creativecommons.org/publicdomain/zero/1.0/
+
+	You can use this content for personal, educational, and commercial purposes.
+
+	Support by crediting 'Kenney' or 'www.kenney.nl' (this is not a requirement)
+
+			------------------------------
+
+	• Website : www.kenney.nl
+	• Donate  : www.kenney.nl/donate
+
+	• Patreon : patreon.com/kenney
+	
+	Follow on social media for updates:
+
+	• Twitter:   twitter.com/KenneyNL
+	• Instagram: instagram.com/kenney_nl
+	• Mastodon:  mastodon.gamedev.place/@kenney

input/entity_picking/assets/models/kenney_prototype-kit/Textures/colormap.png

@@ -0,0 +1,15 @@
+---
+tags: input
+title: Entity Picking
+brief: This example demonstrates how to pick a game object from the 3D scene.
+author: Artsiom Trubchyk
+scripts: entity_picking.script
+---
+
+This example describes method of selecting a game object from the 3D scene on the click of the mouse using collision-based picking:
+
+* We use [collision object components](https://defold.com/manuals/physics-objects/) to define a pickable shape for each relevant game object. This example uses 3D physics, which is enabled in the `game.project` file.
+* When the user clicks the mouse button, we convert screen coordinates to world coordinates and fire a raycast into the 3D world using the `physics.raycast()` function.
+* If the ray intersects with a collision object, the corresponding game object is considered "picked".
+
+The models used in this example are from Kenney's [Prototype Kit](https://kenney.nl/assets/prototype-kit), licensed under CC0.

input/entity_picking/assets/models/kenney_prototype-kit/coin.glb

@@ -0,0 +1,42 @@
+local M = {}
+
+--- Convert a point from 2D screen space to 3D world space. Supports only perspective.
+-- @param x number X coordinate on screen.
+-- @param y number Y coordinate on screen.
+-- @param z number The distance from the camera in world space to create the new point.
+-- @param camera_id url The camera URL to get params from.
+-- @return vector3 The world coordinate.
+function M.screen_to_world(x, y, z, camera_id)
+	-- Camera properties
+	local projection = camera.get_projection(camera_id)
+	assert(projection.m33 == 0.0, "Camera must be in perspective mode")
+
+	local cw, ch = window.get_size()
+	local aspect_ratio = cw / ch
+	local near_z = camera.get_near_z(camera_id)
+	local fov = camera.get_fov(camera_id)
+	local inv_view = vmath.inv(camera.get_view(camera_id))
+
+	-- Calculate the screen click as a point on the far plane of the normalized device coordinate 'box' (z=1)
+	local ndc_x = x / cw * 2 - 1
+	local ndc_y = y / ch * 2 - 1
+
+	-- Calculate perspective projection matrix half size at the near plane
+	local half_size = vmath.vector4(0, 0, -near_z, 1)
+	local h = near_z * math.tan(fov / 2)
+	half_size.x = h * aspect_ratio * ndc_x
+	half_size.y = h * ndc_y
+
+	-- Transform to world space
+	local point = inv_view * half_size
+
+	-- Move to distance z from the camera
+	local world_coord = vmath.normalize(vmath.vector3(point.x - inv_view.m03, point.y - inv_view.m13, point.z - inv_view.m23))
+	world_coord.x = world_coord.x * z + inv_view.m03
+	world_coord.y = world_coord.y * z + inv_view.m13
+	world_coord.z = world_coord.z * z + inv_view.m23
+
+	return world_coord
+end
+
+return M

input/entity_picking/assets/models/kenney_prototype-kit/target-a-round.glb

@@ -0,0 +1,23 @@
+components {
+  id: "coin"
+  component: "/example/coin.script"
+}
+embedded_components {
+  id: "model"
+  type: "model"
+  data: "mesh: \"/assets/models/kenney_prototype-kit/coin.glb\"\n"
+  "name: \"{{NAME}}\"\n"
+  "materials {\n"
+  "  name: \"colormap\"\n"
+  "  material: \"/assets/materials/unlit.material\"\n"
+  "  textures {\n"
+  "    sampler: \"texture0\"\n"
+  "    texture: \"/assets/models/kenney_prototype-kit/Textures/colormap.png\"\n"
+  "  }\n"
+  "}\n"
+  ""
+  rotation {
+    y: 0.70710677
+    w: 0.70710677
+  }
+}

input/entity_picking/assets/models/kenney_prototype-kit/target-a-square.glb

@@ -0,0 +1,7 @@
+function init(self)
+	local start_angle = go.get(".", "euler.y")
+	local to_angle = start_angle - 3600
+
+	-- Simply animate ...
+	go.animate(".", "euler.y", go.PLAYBACK_LOOP_FORWARD, to_angle, go.EASING_LINEAR, 8)
+end