Agent Skills
› ProwlEngine/Prowl
› prowl-physics
prowl-physics
GitHub提供Prowl游戏引擎物理系统开发指南,涵盖射线检测、碰撞查询、CharacterController角色控制及刚体交互等核心API用法与示例。
触发场景
实现角色移动和地面检测
编写射击或碰撞逻辑
处理物理查询和层过滤
安装
npx skills add ProwlEngine/Prowl --skill prowl-physics -g -y
SKILL.md
Frontmatter
{
"name": "prowl-physics",
"description": "Prowl physics for gameplay. Use when writing movement with CharacterController, raycasts or shape casts for shooting and ground checks, layers and query filters, rigidbody projectiles and forces, trigger zones, collision callbacks, or making objects shootable."
}
Prowl physics
Queries
Queries live on the world: SceneInstance.Main.Physics, or the static Physics class for the world whose code is running. SceneInstance is in Prowl.Runtime.Resources. Inside a component, Scene is the component's own nullable Scene property. Queries are main thread only.
Raycast(origin, direction, out RaycastHit hit)andRaycast(origin, direction, maxDistance, out hit).- With a filter, the out comes after the distance:
Raycast(origin, direction, maxDistance, out hit, filter), the same asSphereCast(origin, radius, direction, maxDistance, out hit, filter). RaycastAll(origin, direction, maxDistance, hits)fills a list, nearest first.Linecast(from, to, out hit).SphereCast(origin, radius, direction, maxDistance, out ShapeCastHit hit),OverlapSphere(position, radius, hits),OverlapBox(position, size, rotation, hits). Box sizes are full extents, not half.- The direction is normalized for you.
Hit data:
hit.Point,hit.Normal,hit.Distance,hit.Collider,hit.Transform.- Use
hit.Transform.GameObjectto find what was hit.hit.Collideris null for terrain andhit.Rigidbodyis null for static colliders.
Filters and layers:
new QueryFilter(mask).Ignoring(myBody)skips the shooter. ALayerMaskconverts to aQueryFilterby itself.default(LayerMask)andLayerMask.Everythinghit every layer. Build masks withLayerMask.FromMask(1u << LayerMask.NameToLayer("Enemy")).
using Prowl.Runtime;
using Prowl.Runtime.Resources;
using Prowl.Vector;
public sealed class HitscanGun : Component
{
public float Range = 100f;
public float Damage = 10f;
public Rigidbody3D Owner;
public override void Update()
{
if (!Input.GetMouseButtonDown(0)) return;
QueryFilter filter = Owner.IsValid() ? new QueryFilter(LayerMask.Everything).Ignoring(Owner) : QueryFilter.Default;
if (SceneInstance.Main.Physics.Raycast(Transform.Position, Transform.Forward, Range, out RaycastHit hit, filter))
{
if (hit.Transform.GameObject.TryGetComponent<Health>(out var health)) health.Hurt(Damage);
if (hit.Rigidbody.IsValid()) hit.Rigidbody.ApplyImpulse(Transform.Forward * 2f, hit.Point);
}
}
}
public sealed class Health : Component
{
public float Value = 100f;
public void Hurt(float amount)
{
Value -= amount;
if (Value <= 0f) GameObject.Destroy();
}
}
CharacterController
- The pivot is at the feet.
HeightandRadiusextend up from there. Move(displacement)takes a distance for this frame, not a velocity, and returnsCharacterController.CollisionFlags(Sides,Above,Below). There is noSimpleMoveand no gravity, apply it yourself.IsGrounded,Velocity(what the last move achieved),GroundNormal,GroundVelocity.- Use
Teleport(position)to place it. Setting the Transform directly is not a move. - It never pushes rigidbodies.
- It has no physics body, so raycasts and triggers do not see it as a body. To make the player shootable, add a collider and a kinematic
Rigidbody3Don the controller's own GameObject, which the controller ignores. A body on a child is not ignored, so callcontroller.IgnoreCollisionWith(childBody)for it. - A CharacterController gets no
OnCollisionBeginfor what it walks into. AfterMove, readcontroller.Hits(a list ofShapeCastHit) andcontroller.Collisions.
using System;
using Prowl.Runtime;
using Prowl.Vector;
[RequireComponent(typeof(CharacterController))]
public sealed class FpsMover : Component
{
public float Speed = 5f;
public float JumpHeight = 1.2f;
public float Gravity = 20f;
private CharacterController _controller;
private Float3 _velocity;
public override void OnEnable() => _controller = GetComponent<CharacterController>();
public override void Update()
{
float dt = Time.DeltaTime;
Float2 input = Input.GetWASD();
Float3 wish = (Transform.Forward * input.Y + Transform.Right * input.X) * Speed;
float rising = _velocity.Y;
if (_controller.IsGrounded && rising <= 0f) rising = -2f;
else rising -= Gravity * dt;
if (_controller.IsGrounded && Input.GetKeyDown(KeyCode.Space)) rising = MathF.Sqrt(2f * Gravity * JumpHeight);
_velocity = new Float3(wish.X, rising, wish.Z);
var flags = _controller.Move(_velocity * dt);
if ((flags & CharacterController.CollisionFlags.Above) != 0 && _velocity.Y > 0f) _velocity.Y = 0f;
}
}
Rigidbody3D
MotionType(namespaceJitter2.Dynamics, addusing Jitter2.Dynamics;) isDynamic,KinematicorStatic. There is noisKinematicbool.LinearVelocity,AngularVelocity,Mass,AffectedByGravity,AddForce(force, ForceMode),ApplyImpulse(impulse),MovePosition,MoveRotation.- A collider with no
Rigidbody3Don it or a parent is static. - Interpolation is on by default.
LinearDampingandAngularDamping(0 to 1) are the fraction of velocity removed every physics step, so they are strong: at 60 steps a second, 0.1 leaves under 1 percent of the speed after one second. The defaults are 0.002 and 0.005.- A ball rolled only by torque climbs onto light bodies such as crates instead of pushing them. Add a horizontal force in the direction of travel as well.
Collisions and triggers
OnCollisionBegin,OnCollisionStayandOnCollisionEnd(Collision collision)fire on both sides: on the object with the collider and on the object with the rigidbody.collision.GameObjectis the other object andcollision.Normalpoints toward this side.- Colliders have no trigger flag. Add a
TriggerVolumecomponent instead.OnTriggerEnter/Stay/Exit(Rigidbody3D other)then fire on the trigger's own GameObject, for bodies with aRigidbody3D. Character controllers entering it raiseOnCharacterEnter/Stay/Exit(CharacterController controller)instead. TriggerVolume.OverlappingandOverlappingCharacterslist what is inside right now.
Look up PhysicsWorld, CharacterController, Rigidbody3D, TriggerVolume, QueryFilter and ShapeCastHit with api --type.
版本历史
- f68efb0 当前 2026-11-21 16:09


