Skip to content

README.md

Latest commit

 

History

History
146 lines (99 loc) · 4.81 KB

README.md

File metadata and controls

146 lines (99 loc) · 4.81 KB

ZonePlus - Modern Spatial Query Edition

Documentation

ZonePlus is a powerful and efficient zone detection library for Roblox, now fully modernized to leverage Roblox's latest spatial query APIs.

🚀 What's New - Modern Spatial Query Update (v4.0.0)

ZonePlus has been completely modernized to use Roblox's current spatial query APIs:

Key Improvements

✅ Modern Spatial Query APIs

  • Replaced deprecated Region3 with CFrame + Size approach
  • Full integration with WorldRoot:GetPartBoundsInBox
  • Full integration with WorldRoot:GetPartBoundsInRadius for spherical zones
  • Full integration with WorldRoot:GetPartsInPart for precise geometry checks

✅ Updated FilterType Enums

  • Migrated from deprecated Whitelist/Blacklist to modern Include/Exclude
  • Optimized OverlapParams reuse for better performance

✅ New Zone Shape Support

  • Zone.fromBox(cframe, size) - Optimized box-shaped zones using GetPartBoundsInBox
  • Zone.fromSphere(position, radius) - Optimized spherical zones using GetPartBoundsInRadius
  • Auto-detection for optimal spatial query method based on zone geometry

✅ Performance Optimizations

  • Reusable OverlapParams objects to reduce garbage collection
  • Smart spatial query method selection based on zone shape
  • Efficient filtering using modern collision detection

📚 Spatial Query API Comparison

Roblox Spatial Query Methods Used

API Method Use Case Performance
GetPartBoundsInBox Box-shaped zones (rotated/aligned) ⚡ Very Fast (bounding box)
GetPartBoundsInRadius Spherical/radial zones ⚡ Very Fast (bounding box)
GetPartsInPart Precise geometry checks ⚠️ Slower (precise overlap)

ZonePlus automatically selects the best method based on your zone configuration.

🎯 Quick Start

local Zone = require(game.ReplicatedStorage.Zone)

-- Create a traditional zone from a container
local container = workspace.SafeZone
local zone = Zone.new(container)

-- Or create an optimized box zone
local boxZone = Zone.fromBox(
    CFrame.new(0, 10, 0),
    Vector3.new(50, 20, 50)
)

-- Or create an optimized spherical zone
local sphereZone = Zone.fromSphere(
    Vector3.new(0, 10, 0),
    25 -- radius
)

-- Connect to events
zone.playerEntered:Connect(function(player)
    print(player.Name .. " entered the zone!")
end)

zone.playerExited:Connect(function(player)
    print(player.Name .. " left the zone!")
end)

🔧 Advanced Configuration

Zone Shape Optimization

-- Manually set the spatial query method
zone:setZoneShape("Box")    -- Use GetPartBoundsInBox
zone:setZoneShape("Sphere") -- Use GetPartBoundsInRadius
zone:setZoneShape("Auto")   -- Auto-detect (default)

Detection Modes

-- Set detection precision
zone:setAccuracy("High")    -- 0.1 second checks
zone:setAccuracy("Medium")  -- 0.5 second checks
zone:setAccuracy("Low")     -- 1.0 second checks
zone:setAccuracy("Precise") -- Every frame (0.0)

-- Set detection method
zone:setDetection("Centre")    -- Check HumanoidRootPart only (faster)
zone:setDetection("WholeBody") -- Check entire character (more accurate)

📖 Documentation

For comprehensive documentation including:

  • API reference
  • Advanced examples
  • Best practices
  • Migration guides

Visit the ZonePlus Documentation Site

💡 Performance Tips

  1. Reuse OverlapParams: ZonePlus now automatically reuses OverlapParams objects
  2. Choose the right shape: Use fromSphere() for radial zones, fromBox() for rectangular zones
  3. Optimize accuracy: Use lower accuracy settings when possible
  4. Use Centre detection: For large zones with many players, Centre detection is much faster

🔄 Migration from Old Region3 Code

If you were using older ZonePlus versions, your existing code will continue to work! The modernization is backward-compatible. However, we recommend:

  1. Using the new fromBox() and fromSphere() constructors for new zones
  2. Checking that zones work as expected (internal representation changed from Region3 to CFrame+Size)

🐛 Known Limitations

  • Collision group edge cases: Parts in the same collision group may not always be detected (Roblox engine limitation)
  • Performance with distant parts: Many parts far from query regions can cause performance degradation (Roblox engine limitation)

📝 License

See LICENSE file for details.

🙏 Credits

Original ZonePlus by nanoblox Modern Spatial Query Update - 2025

For support and discussions, visit the DevForum thread