Skip to content

Commit 8774085

Browse files
paweljaroszpaweljarosz
authored
Added Box2D material tuning example (#195)
* Added Box2D material tuning example * Added a chain Box2D scripting example. * Updated example to support both V2 and V3. * Remove chain example from this PR. * Changed example to spawn 3 balls in similar positions, with no velocity and rotation. Improved description. Updated thumbnail.
1 parent 59c0e3e commit 8774085

20 files changed

Lines changed: 1405 additions & 0 deletions

‎physics/box2d_material_tuning/all.texture_profiles‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
path_settings {
2+
path: "**"
3+
profile: "Default"
4+
}
5+
profiles {
6+
name: "Default"
7+
platforms {
8+
os: OS_ID_GENERIC
9+
formats {
10+
format: TEXTURE_FORMAT_RGBA
11+
compression_level: BEST
12+
compression_type: COMPRESSION_TYPE_DEFAULT
13+
}
14+
mipmaps: false
15+
max_texture_size: 0
16+
premultiply_alpha: true
17+
}
18+
}

‎physics/box2d_material_tuning/box2d_v2.appmanifest‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
platforms:
2+
arm64-ios:
3+
context:
4+
excludeLibs: []
5+
excludeSymbols: []
6+
symbols: []
7+
libs: []
8+
frameworks: []
9+
linkFlags: []
10+
x86_64-ios:
11+
context:
12+
excludeLibs: []
13+
excludeSymbols: []
14+
symbols: []
15+
libs: []
16+
frameworks: []
17+
linkFlags: []
18+
armv7-android:
19+
context:
20+
excludeLibs: []
21+
excludeJars: []
22+
excludeSymbols: []
23+
symbols: []
24+
libs: []
25+
linkFlags: []
26+
jetifier: true
27+
arm64-android:
28+
context:
29+
excludeLibs: []
30+
excludeJars: []
31+
excludeSymbols: []
32+
symbols: []
33+
libs: []
34+
linkFlags: []
35+
jetifier: true
36+
arm64-osx:
37+
context:
38+
excludeLibs: []
39+
excludeSymbols: []
40+
symbols: []
41+
libs: []
42+
frameworks: []
43+
linkFlags: []
44+
x86_64-osx:
45+
context:
46+
excludeLibs: []
47+
excludeSymbols: []
48+
symbols: []
49+
libs: []
50+
frameworks: []
51+
linkFlags: []
52+
x86_64-linux:
53+
context:
54+
excludeLibs: []
55+
excludeSymbols: []
56+
symbols: []
57+
libs: []
58+
linkFlags: []
59+
arm64-linux:
60+
context:
61+
excludeLibs: []
62+
excludeSymbols: []
63+
symbols: []
64+
libs: []
65+
linkFlags: []
66+
x86-win32:
67+
context:
68+
excludeLibs: []
69+
excludeSymbols: []
70+
symbols: []
71+
libs: []
72+
linkFlags: []
73+
x86_64-win32:
74+
context:
75+
excludeLibs: []
76+
excludeSymbols: []
77+
symbols: []
78+
libs: []
79+
linkFlags: []
80+
wasm-web:
81+
context:
82+
excludeLibs: []
83+
excludeJsLibs: []
84+
excludeSymbols: []
85+
symbols: []
86+
libs: []
87+
linkFlags: []
88+
wasm_pthread-web:
89+
context:
90+
excludeLibs: []
91+
excludeJsLibs: []
92+
excludeSymbols: []
93+
symbols: []
94+
libs: []
95+
linkFlags: []

‎physics/box2d_material_tuning/box2d_v3.appmanifest‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
platforms:
2+
armv7-ios:
3+
context:
4+
excludeLibs: [physics, box2d_defold, script_box2d_defold]
5+
excludeSymbols: []
6+
libs: [physics_2d, box2d, script_box2d, physics_3d]
7+
arm64-ios:
8+
context:
9+
excludeLibs: [physics, box2d_defold, script_box2d_defold]
10+
excludeSymbols: []
11+
symbols: []
12+
libs: [physics_2d, box2d, script_box2d, physics_3d]
13+
frameworks: []
14+
linkFlags: []
15+
x86_64-ios:
16+
context:
17+
excludeLibs: [physics, box2d_defold, script_box2d_defold]
18+
excludeSymbols: []
19+
symbols: []
20+
libs: [physics_2d, box2d, script_box2d, physics_3d]
21+
frameworks: []
22+
linkFlags: []
23+
armv7-android:
24+
context:
25+
excludeLibs: [physics, box2d_defold, script_box2d_defold]
26+
excludeJars: []
27+
excludeSymbols: []
28+
symbols: []
29+
libs: [physics_2d, box2d, script_box2d, physics_3d]
30+
linkFlags: []
31+
jetifier: true
32+
arm64-android:
33+
context:
34+
excludeLibs: [physics, box2d_defold, script_box2d_defold]
35+
excludeJars: []
36+
excludeSymbols: []
37+
symbols: []
38+
libs: [physics_2d, box2d, script_box2d, physics_3d]
39+
linkFlags: []
40+
jetifier: true
41+
arm64-osx:
42+
context:
43+
excludeLibs: [physics, box2d_defold, script_box2d_defold]
44+
excludeSymbols: []
45+
symbols: []
46+
libs: [physics_2d, box2d, script_box2d, physics_3d]
47+
frameworks: []
48+
linkFlags: []
49+
x86_64-osx:
50+
context:
51+
excludeLibs: [physics, box2d_defold, script_box2d_defold]
52+
excludeSymbols: []
53+
symbols: []
54+
libs: [physics_2d, box2d, script_box2d, physics_3d]
55+
frameworks: []
56+
linkFlags: []
57+
x86_64-linux:
58+
context:
59+
excludeLibs: [physics, box2d_defold, script_box2d_defold]
60+
excludeSymbols: []
61+
symbols: []
62+
libs: [physics_2d, box2d, script_box2d, physics_3d]
63+
linkFlags: []
64+
arm64-linux:
65+
context:
66+
excludeLibs: [physics, box2d_defold, script_box2d_defold]
67+
excludeSymbols: []
68+
symbols: []
69+
libs: [physics_2d, box2d, script_box2d, physics_3d]
70+
linkFlags: []
71+
x86-win32:
72+
context:
73+
excludeLibs: [libphysics, libbox2d_defold, script_box2d_defold]
74+
excludeSymbols: []
75+
symbols: []
76+
libs: [libphysics_2d.lib, libbox2d.lib, libscript_box2d.lib, libphysics_3d.lib]
77+
linkFlags: []
78+
x86_64-win32:
79+
context:
80+
excludeLibs: [libphysics, libbox2d_defold, script_box2d_defold]
81+
excludeSymbols: []
82+
symbols: []
83+
libs: [libphysics_2d.lib, libbox2d.lib, libscript_box2d.lib, libphysics_3d.lib]
84+
linkFlags: []
85+
wasm-web:
86+
context:
87+
excludeLibs: [physics, box2d_defold, script_box2d_defold]
88+
excludeJsLibs: []
89+
excludeSymbols: []
90+
symbols: []
91+
libs: [physics_2d, box2d, script_box2d, physics_3d]
92+
linkFlags: []
93+
wasm_pthread-web:
94+
context:
95+
excludeLibs: [physics, box2d_defold, script_box2d_defold]
96+
excludeJsLibs: []
97+
excludeSymbols: []
98+
symbols: []
99+
libs: [physics_2d, box2d, script_box2d, physics_3d]
100+
linkFlags: []

‎physics/box2d_material_tuning/example.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
tags: physics, box2d
3+
title: Box2D Material Properties Tuning
4+
brief: Tune Box2D density, friction, and restitution from script using Box2D V2 legacy and Box2D V3.
5+
author: Defold Foundation
6+
scripts: box2d_material_tuning_v3.script, box2d_material_tuning_v2.script
7+
thumbnail: thumbnail.webp
8+
---
9+
10+
This example compares three dynamic balls whose Box2D material properties are tuned from script. It works with both Box2D V2 legacy and Box2D V3 by attaching one script for each backend. Each script checks `b2d.get_version()` during `init()` and becomes a no-op when the other backend is active.
11+
12+
Click or tap the window to reset the balls and watch the comparison again.
13+
14+
## What You'll Learn
15+
16+
* How to get a Box2D body from a Defold collision object
17+
* How to detect the active Box2D version with `b2d.get_version()`
18+
* How to tune density, friction, and restitution through the V2 fixture API
19+
* How to tune density, friction, and restitution through the V3 shape API
20+
* How to switch the project between Box2D V2 and V3 with app manifests
21+
22+
## Setup
23+
24+
The collection contains three spawner game objects, one for each material: Ice, Rubber, and Gold. Each spawner has both backend scripts, a label, and a local factory component named `ball_factory`.
25+
26+
All three factories point at `/example/ball.go`, a shared prototype with one sprite and one dynamic circle collision object. The active script creates a ball at the spawner's position, tints the spawned sprite, applies the material settings, and gives it a starting velocity and spin from the spawner's script properties.
27+
28+
The material comparison comes from per-instance script property overrides:
29+
30+
<kbd>Ice</kbd>
31+
: Low friction and low restitution, so the ball slides along the ramp.
32+
33+
<kbd>Rubber</kbd>
34+
: Medium friction and high restitution, so the ball bounces more.
35+
36+
<kbd>Gold</kbd>
37+
: High density, high friction, and low restitution, so the ball feels heavier and settles quickly.
38+
39+
The static scene is built from white walls, and three colored ramps.
40+
41+
![setup](setup.png)
42+
43+
The `game.project` of this example is configured to build with `/box2d_v3.appmanifest` by default. To test V2 locally after downloading the example, change `Native Extensions -> App Manifest` in `game.project` to `/box2d_v2.appmanifest`.
44+
45+
![game_project](game_project.png)
46+
47+
## How It Works
48+
49+
Both scripts read `b2d.get_version()` once. `box2d_material_tuning_v2.script` only continues when the major version is 2, while `box2d_material_tuning_v3.script` only continues when the major version is 3.
50+
51+
`go.property()` exposes the material settings on each script instance. The Ice, Rubber, and Gold spawners use the same scripts, but each spawner overrides density, friction, restitution, velocity, spin, tint, and material name in the collection.
52+
53+
`b2d.get_body()` returns the Box2D body owned by the spawned ball's collision object. The active script then updates the ball with the backend-specific material API.
54+
55+
There is a significant difference between Box2D V2 legacy and Box2D V3.
56+
57+
In Box2D V2 legacy, collision geometry and material properties are attached to a body through fixtures. The V2 script reads the first fixture with `b2d.body.get_fixtures()` and uses `b2d.fixture.set_density()`, `b2d.fixture.set_friction()`, and `b2d.fixture.set_restitution()` to tune the ball. When setting density, the script asks Box2D to update the body mass from the new value.
58+
59+
In Box2D V3, the script uses the shape API instead of the V2 fixture API. It reads the first shape with `b2d.body.get_shapes()` and uses `b2d.shape.set_density()`, `b2d.shape.set_friction()`, and `b2d.shape.set_restitution()`. After changing density, it calls `b2d.body.reset_mass_data()` so the body mass reflects the new density immediately.
60+
61+
After applying the values, each script reads them back and shows them on the label attached to the same spawner. Clicking or tapping makes each active spawner delete its current ball, spawn a fresh one from its own factory, and reapply its material settings for the current backend.

‎physics/box2d_material_tuning/example/ball.go‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
embedded_components {
2+
id: "sprite"
3+
type: "sprite"
4+
data: "default_animation: \"ball\"\n"
5+
"material: \"/builtins/materials/sprite.material\"\n"
6+
"size {\n"
7+
" x: 254.0\n"
8+
" y: 254.0\n"
9+
"}\n"
10+
"textures {\n"
11+
" sampler: \"texture_sampler\"\n"
12+
" texture: \"/textures/textures.atlas\"\n"
13+
"}\n"
14+
""
15+
scale {
16+
x: 0.5
17+
y: 0.5
18+
}
19+
}
20+
embedded_components {
21+
id: "collisionobject"
22+
type: "collisionobject"
23+
data: "type: COLLISION_OBJECT_TYPE_DYNAMIC\n"
24+
"mass: 1.0\n"
25+
"friction: 0.2\n"
26+
"restitution: 0.2\n"
27+
"group: \"default\"\n"
28+
"mask: \"default\"\n"
29+
"embedded_collision_shape {\n"
30+
" shapes {\n"
31+
" shape_type: TYPE_SPHERE\n"
32+
" position {\n"
33+
" }\n"
34+
" rotation {\n"
35+
" }\n"
36+
" index: 0\n"
37+
" count: 1\n"
38+
" }\n"
39+
" data: 32.0\n"
40+
"}\n"
41+
""
42+
}

0 commit comments

Comments
 (0)