Física 3D
Consultas por raio e forças no mundo 3D Bullet. Tudo é um no-op seguro (false ou nil) quando o host corre sem física 3D. Forças e velocidade só afetam corpos dinâmicos.
Namespace: caffeine.physics3d · Dryad prefix: caffeine_physics3d_
isAvailable#
Lua: caffeine.physics3d.isAvailable · Dryad: caffeine_physics3d_available
isAvailable() -> boolean
Indica se a física 3D pode ser usada.
Devolve: boolean. true quando há um mundo de física 3D e o backend Bullet está compilado.
Exemplo
if not caffeine.physics3d.isAvailable() then caffeine.debug.warn("no 3D physics") end
setGravity#
Lua: caffeine.physics3d.setGravity · Dryad: caffeine_physics3d_set_gravity
setGravity(x, y, z)
Define o vetor de gravidade em metros por segundo ao quadrado (por omissão 0, -9.81, 0).
| Parâmetros | Tipo | Descrição |
|---|---|---|
x | number | Componente X. |
y | number | Componente Y. |
z | number | Componente Z. |
Devolve: nada
Exemplo
caffeine.physics3d.setGravity(0, -3.7, 0) -- Mars
raycast#
Lua: caffeine.physics3d.raycast · Dryad: caffeine_physics3d_raycast
raycast(ox, oy, oz, dx, dy, dz, maxDistance) -> table | nil
Lança um raio e devolve o primeiro corpo sólido que atinge, com o ponto de impacto e a normal da superfície.
| Parâmetros | Tipo | Descrição |
|---|---|---|
ox, oy, oz | number | Origem do raio no espaço do mundo. |
dx, dy, dz | number | Direção; não precisa de estar normalizada. |
maxDistance | number | Comprimento máximo em metros. |
Devolve: table | nil. { entity, x, y, z, nx, ny, nz, distance } para o corpo mais próximo atingido, ou nil. Os triggers são ignorados.
Exemplo
local hit = caffeine.physics3d.raycast(0, 10, 0, 0, -1, 0, 100)
if hit then caffeine.debug.log(hit.entity .. " at " .. hit.distance) end
addForce#
Lua: caffeine.physics3d.addForce · Dryad: caffeine_physics3d_add_force
addForce(entity, x, y, z) -> boolean
Aplica uma força (newtons) no centro de massa no próximo passo de física.
| Parâmetros | Tipo | Descrição |
|---|---|---|
entity | number | Um corpo com RigidBody3D e Collider3D. |
x | number | Componente X. |
y | number | Componente Y. |
z | number | Componente Z. |
Devolve: boolean. false para um corpo desconhecido ou não dinâmico.
Exemplo
caffeine.physics3d.addForce(eid, 0, 50, 0)
addImpulse#
Lua: caffeine.physics3d.addImpulse · Dryad: caffeine_physics3d_add_impulse
addImpulse(entity, x, y, z) -> boolean
Aplica uma mudança instantânea de momento (newton-segundos) no centro de massa, por exemplo um salto.
| Parâmetros | Tipo | Descrição |
|---|---|---|
entity | number | Um corpo com RigidBody3D e Collider3D. |
x | number | Componente X. |
y | number | Componente Y. |
z | number | Componente Z. |
Devolve: boolean. false para um corpo desconhecido ou não dinâmico.
Exemplo
caffeine.physics3d.addImpulse(eid, 0, 6, 0)
setVelocity#
Lua: caffeine.physics3d.setVelocity · Dryad: caffeine_physics3d_set_velocity
setVelocity(entity, x, y, z) -> boolean
Define a velocidade linear em metros por segundo.
| Parâmetros | Tipo | Descrição |
|---|---|---|
entity | number | Um corpo com RigidBody3D e Collider3D. |
x | number | Componente X. |
y | number | Componente Y. |
z | number | Componente Z. |
Devolve: boolean. false para um corpo desconhecido ou não dinâmico.
Exemplo
caffeine.physics3d.setVelocity(eid, 4, 0, 0)
velocity#
Lua: caffeine.physics3d.velocity · Dryad: caffeine_physics3d_velocity
velocity(entity) -> table | nil
Lê a velocidade linear de um corpo.
| Parâmetros | Tipo | Descrição |
|---|---|---|
entity | number | Um corpo com RigidBody3D e Collider3D. |
Devolve: table | nil. { x, y, z } em metros por segundo, ou nil para um corpo desconhecido ou não dinâmico.
Exemplo
local v = caffeine.physics3d.velocity(eid)