[READ-ONLY] Mirror of https://github.com/excaliburjs/Excalibur. 🎮 Your friendly TypeScript 2D game engine for the web 🗡️
excaliburjs.com
excalibur
excaliburjs
game-development
game-engine
game-framework
gamedev
games
html5-canvas
typescript
docs: Update raycast docs
Erik Onarheim
(May 8, 2024, 8:24 PM -0500)
90dfd8da
42933d01
+106
+106
site/docs/09-math/07-ray.mdx
+106
site/docs/09-math/07-ray.mdx
···
6
6
7
7
[[Ray]]'s are a useful tool for testing if geometry intersects a line of sight with [[Collider.rayCast]]. You can think of them as a point in space with a direction.
8
8
9
+
Examples where ray casting can be useful
10
+
* Custom physics implementations (platformers, slopes, etc)
11
+
* Line of sight AI
12
+
* Proximity detection
13
+
14
+
:::warning
15
+
16
+
If you start a raycast from inside an [[Actor]] it will hit that Actor first unless you explicitly exclude it. See Raycast Options below.
17
+
18
+
:::
19
+
20
+
## Scene Testing
21
+
22
+
It is possible to test against all actors in a [[Scene]] at once.
23
+
24
+
```typescript
25
+
26
+
// given a scene reference
27
+
const game = new ex.Engine({...});
28
+
game.start();
29
+
30
+
31
+
const ray = new ex.Ray(ex.vec(100, 100), ex.Vector.Right);
32
+
game.currentScene.physics.rayCast(ray, {...});
33
+
34
+
// or in a custom scene
35
+
class MyScene extends ex.Scene {
36
+
37
+
someRayTestMethod() {
38
+
39
+
const ray = new ex.Ray(ex.vec(100, 100), ex.Vector.Right);
40
+
this.physics.rayCast(ray, {...});
41
+
}
42
+
}
43
+
44
+
```
45
+
46
+
## Scene Raycast Options
47
+
48
+
Excalibur's raycast can be optionally configured in a variety of ways. By default if no options are provided to the `rayCast(ray, ...)` the options will be
49
+
50
+
```typescript
51
+
const hits = scene.physics.rayCast(ray, {
52
+
searchAllColliders: true,
53
+
collisionGroup: CollisionGroup.All,
54
+
collisionMask: CollisionGroup.All.mask,
55
+
ignoreCollisionGroupAll: false,
56
+
maxDistance: Infinity,
57
+
filter: null,
58
+
})
59
+
```
60
+
61
+
### Search All Colliders
62
+
63
+
By default the raycast will not stop after the first hit is found, if you'd like to only get the first hit set `searchAllColliders: false`
64
+
65
+
### Max Distance
66
+
67
+
Distance is in terms of pixels, this is the maximum length along the ray to search for colliders.
68
+
69
+
### Hit Filtering
70
+
71
+
Using the `filter` option you can do complex filtering logic to reject or accept potential hits.
72
+
73
+
```typescript
74
+
scene.physics.rayCast(ray, {
75
+
filter: (potentialHit: RayCastHit) => {
76
+
// return true to accept the hit
77
+
// return false to reject the hit
78
+
return true;
79
+
}
80
+
})
81
+
```
82
+
83
+
### Collision Mask
84
+
85
+
The collision mask it a bit mask with a 1 in the place for each collision group category you'd like to consider in the raycast. For example this is useful if all your enemies share a collision group category. See [collision group documentation](/docs/collisiongroups/) for more information.
86
+
87
+
You may want to pair this with `ignoreCollisionGroupAll: true` to avoid default actors which collide with everything including specific rayCast masks.
88
+
89
+
```typescript
90
+
const playerGroup = new ex.CollisionGroup('player', 0b0001, ~0b0001);
91
+
const enemyGroup = new ex.CollisionGroup('enemy', 0b0010, ~0b0010);
92
+
...
93
+
94
+
// this raycast will only actors with the 1 in the second place, so enemyGroup
95
+
const enemyHits = scene.physics.rayCast(ray, {
96
+
collisionMask: 0b0010;
97
+
});
98
+
99
+
// this raycast will only actors with the 1 in the first and second place, so playerGroup and enemyGroup
100
+
const playerAndEnemyHits = scene.physics.rayCast(ray, {
101
+
collisionMask: 0b0011;
102
+
});
103
+
```
104
+
105
+
### Collision Group
106
+
107
+
The `collisionGroup` searches for actors that match a specific collision group.
108
+
109
+
You may want to pair this with `ignoreCollisionGroupAll: true` to avoid default actors which collide with everything including specific rayCast groups.
110
+
111
+
## Specific Actor Geometry Testing
112
+
113
+
If you have a specific actor or geometry that you know you will test against, all [[Collider]] types implement `rayCast(ray, [maxDistance])`.
114
+
9
115
```typescript
10
116
const actor = new ex.Actor({
11
117
pos: ex.vec(200, 100),