roblox-physics
Roblox physics and spatial queries: assemblies, constraints, collision groups, Raycast and Shapecast, and network ownership
Install / Use
npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill roblox-physicsInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of roblox-physics
roblox-physics scores 94/100 on our quality scale, 435th of 4,700 Development & Engineering skills we index (top 10%).
Its SKILL.md is 7.8 KB long, well organised into 11 sections with 2 code examples: a thorough specification that gives an agent plenty to work with.
With 8,904 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated 4 days ago, so roblox-physics is actively maintained.
- Our last check on 2026-11-16 found the source still online.
- It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-08. Automated pattern scan on 2026-10-08. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
roblox-physics compared with similar skills
All 4 of these similar skills score higher than roblox-physics; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| roblox-physics (this skill)by gamedev-skills | 94 | 8.9k | 4d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
Frequently asked questions
- How do I install roblox-physics?
- Run
npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill roblox-physics. The install tabs above show the steps for each supported agent. - Which AI agents does roblox-physics work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is roblox-physics safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is roblox-physics still maintained?
- The repository was last updated 4 days ago, so roblox-physics is actively maintained.
Skill content
View source on GitHubname: roblox-physics description: > Implement Roblox physical simulation and queries with assemblies, anchoring, constraints, collision groups, CanCollide/CanTouch/CanQuery, raycasts and overlap queries, mass, impulses, forces, velocity, moving assemblies, cleanup, and network ownership. Use for Roblox collisions, hit detection, RaycastParams, PhysicsService, projectiles, vehicles, knockback, constraints, deprecated BodyMovers, unstable motion, or client-owned physics exploits.
Roblox physics
Choose deliberately between simulation, character control, hit detection, and visual-only motion;
they are different jobs. Targets Roblox's rolling platform APIs. Pair with physics-tuning for
engine-neutral stability and feel.
When to use
- Use for BasePart assemblies, constraints, collision/query policy, ray/overlap queries, forces, impulses, moving physical objects, network ownership, or physics cleanup.
- Use when
Touchedis unreliable/security-sensitive, parts tunnel or jitter, a mechanism breaks when anchored, or old BodyMover patterns appear.
When not to use: ordinary Humanoid lifecycle/control belongs to roblox-characters; remote
validation belongs to roblox-networking; decorative UI/world motion may only need a tween.
Decide the system first
| Goal | Mechanism |
|---|---|
| sustained physical interaction | unanchored assembly + modern constraints/forces |
| instantaneous physical change | ApplyImpulse / ApplyAngularImpulse |
| kinematic platform/path | controlled pivot/transform with an explicit passenger policy |
| character locomotion | Humanoid/custom character controller (roblox-characters) |
| authoritative hit test | server raycast/overlap with filters and gameplay validation |
| cosmetic trail/recoil | local visual motion; no gameplay authority |
Workflow
- Inspect the mechanism. In Studio, visualize assemblies, anchors, constraints, collision groups, massless parts, and network owners. Identify the assembly root and intended authority.
- Define interaction policy. Write the collision-group matrix and separately decide
CanCollide,CanTouch, andCanQuery. These flags are not interchangeable. - Choose simulation or query. Do not use
.Touchedas a universal hit detector. Use a ray for a path/line, an overlap query for a volume, and simulation contacts when physical response is actually required. - Apply motion at assembly level. Forces on a part affect its assembly. Use modern
LinearVelocity,AngularVelocity,VectorForce,AlignPosition, andAlignOrientationconstraints as appropriate; migrate deprecated BodyMovers when changing that system. - Set ownership deliberately. Server-own gameplay-critical loose assemblies when required; client ownership can improve responsiveness but never authorizes gameplay results.
- Bound cost and lifetime. Reuse query parameters, cap query frequency/result count, remove temporary constraints/attachments, and disconnect event listeners.
- Verify under load and multiplayer. Test anchored/unanchored transitions, mass extremes, collision matrix, fast motion, multiple clients, ownership changes, streaming, and cleanup.
Pattern: filtered server raycast
local Workspace = game:GetService("Workspace")
local params = RaycastParams.new()
params.FilterType = Enum.RaycastFilterType.Exclude
params.FilterDescendantsInstances = {shooterCharacter}
params.IgnoreWater = true
params.CollisionGroup = "WeaponQuery"
local direction = aimDirection.Unit * MAX_RANGE
local result = Workspace:Raycast(muzzlePosition, direction, params)
if result then
local model = result.Instance:FindFirstAncestorOfClass("Model")
local humanoid = model and model:FindFirstChildOfClass("Humanoid")
if humanoid and serverCanDamage(shooter, model, result.Position) then
humanoid:TakeDamage(serverWeaponDamage(shooter))
end
end
The server must validate the origin/direction against server-known character/weapon state; do not accept an arbitrary client origin and treat the raycast itself as validation.
Pattern: overlap volume with explicit policy
local params = OverlapParams.new()
params.FilterType = Enum.RaycastFilterType.Exclude
params.FilterDescendantsInstances = {sourceCharacter}
params.CollisionGroup = "DamageQuery"
params.MaxParts = 64
local seen: {[Model]: boolean} = {}
for _, part in Workspace:GetPartBoundsInBox(hitboxCFrame, hitboxSize, params) do
local model = part:FindFirstAncestorOfClass("Model")
if model and not seen[model] then
seen[model] = true
validateAndApplyHit(model)
end
end
Bounds queries use bounding boxes and can include multiple parts from one target; deduplicate and
perform exact/gameplay checks as needed. For exact geometry use WorldRoot:GetPartsInPart(part, overlapParams)
only when its additional cost is justified. Note OverlapParams.RespectCanCollide decides whether a
query honours CanCollide or CanQuery — set it deliberately, or it silently overrides the flag
policy below. OverlapParams.Tolerance controls contact slop.
Assemblies, force, and ownership
- Welded parts form one rigid assembly; force, impulse, velocity, mass, and ownership operate on that assembly. Anchoring a part changes simulation/ownership and can make an assembly effectively infinite mass.
- Apply an impulse for a one-time change; use a force or velocity constraint for sustained control.
Setting
AssemblyLinearVelocityis an immediate state change, not a continuous force model. - Prefer attachments plus modern constraints over
BodyPosition,BodyVelocity,BodyGyro, and other deprecated BodyMovers when authoring or revising a mechanism. - Automatic ownership may move nearby unanchored assemblies to clients. Use
SetNetworkOwner(nil)conservatively for critical objects, then measure responsiveness/server cost. Visualize network owners in Studio. - A client owner can manipulate physical results and
.Touchedobservations. The server validates consequential hits, positions, timing, and permissions independently.
Common failures
| Symptom | Likely cause | Remedy |
|---|---|---|
| welded mechanism will not move | one part anchored | inspect full assembly; anchor only intentional world roots |
| force behaves too strongly/weakly | assembly mass ignored | inspect AssemblyMass; tune force/impulse by intended acceleration |
| hit misses fast projectile | discrete touch sampling/tunneling | swept query — WorldRoot:Blockcast(), Spherecast(), or Shapecast() — plus physics-tuning; do not rely only on .Touched |
| ray hits shooter/effects | filters/collision group absent | reuse explicit params and query group |
| same target damaged many times | overlap returned multiple body parts | deduplicate by target model and enforce attack ID/cooldown |
| exploit fires impossible touch | client owns relevant physics | server query/context validation; deliberate ownership |
| invisible trigger blocks or cannot query | three flags conflated | set CanCollide, CanTouch, CanQuery independently |
| mechanism leaks attachments | temporary constraint lifecycle missing | own and destroy constraints, attachments, and connections together |
Resources
- Read
references/queries-and-ownership.mdfor collision/query matrices, assembly debugging, ownership security, migration choices, and the physics verification matrix.
Related skills
physics-tuning— timestep, jitter, tunneling, mass ratios, and stability methodology.roblox-characters— Humanoid/custom movement and respawn lifecycle.roblox-networking— authoritative validation of client-requested physical actions.roblox-studio-workflow— visualization, Output, and multi-client verification.
Primary references
https://create.roblox.com/docs/physics/assemblieshttps://create.roblox.com/docs/physics/network-ownershiphttps://create.roblox.com/docs/workspace/raycasting
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
