GPU

Static adapter info. Cached, calling repeatedly is free. Useful for logging, settings menus, and gating high-cost features behind DeviceType == "DiscreteGpu".

Hard limits the active GPU device reports. wgpu doesn't expose total VRAM portably across DX12 / Vulkan / Metal, MaxBufferSize is the closest single number for "biggest thing I can allocate".

FPS / frame time / scene part count. Updated once per heart tick. Cheap; safe to poll every frame for a debug overlay.

GPU-dispatched ray test against every renderable BasePart. One compute thread per part runs in parallel: cubes test as oriented bounding boxes (CFrame + Size), spheres as ellipsoids (CFrame + Size), and models with mesh data test per-triangle via Möller-Trumbore in part-local space, so corners and concavities hit precisely instead of bounding boxes. Models without mesh data fall back to OBB. Parts with Render = false or IgnoreInRaycast = true are skipped. Falls back to a CPU loop only if the GPU has not been initialized (i.e. no window opened yet).

Convert a screen pixel (Mouse.Position style) to a world-space ray. Returns (origin, direction), feed straight into GPU.Raycast. Uses the active Renderable.Camera as the eye + projection.

Project a world-space point onto the screen. (Dim, false) when the point is in front of the camera; (nil, true) when at or behind the near plane. Useful for billboards, world-anchored UI, off-screen indicators.

Allocate a GPU storage buffer of size floats. Memory lives on the GPU. Freed when the GPUBuffer userdata is garbage-collected.

Bind a GPUBuffer as the active SDATA storage. Cheap to swap between frames, bind groups are rebuilt only when the binding identity changes.

Unbind the active storage buffer. SDATA reverts to a 1-float stub so shaders that don't reference it keep working.

Cap or uncap the heart-loop tick rate. Pass nil (or 0) to remove the cap and run as fast as the system allows; pass a positive number to throttle. The engine ships uncapped — frames run as fast as the renderer + game logic allow, bounded only by the swapchain present mode (see SetVSync). The cap is applied by sleeping at the end of each tick if the frame finished early, so it has no effect on a system that can't keep up. Cheap to call live (atomic store), wire it to a settings menu freely.

Current cap, or nil when uncapped.

Toggle vertical sync on the swapchain. Default is OFF — the engine picks the highest-FPS tear-free mode the driver offers (Mailbox > Immediate > FifoRelaxed > Fifo). Turning VSync on hard-caps presents to the monitor's refresh rate (Fifo / FifoRelaxed). Use it for laptop battery life or to eliminate tearing on monitors that don't expose a tear-free uncapped mode. Takes effect on the next rendered frame.

True if the swapchain is currently in a VSync mode.

Set the GPU power-mode preference. Three options:

• "Quality" — default. Requests the HighPerformance adapter (discrete GPU on dual-GPU laptops) and biases the driver toward high clocks. Best for shooters / action games where you want the highest sustained FPS the hardware can give you.
• "Performance" — despite the name, the battery-friendly mode. Requests the LowPower adapter (integrated GPU when present) and lets the driver downclock aggressively. Use for lightweight / stylized games where you'd rather extend laptop battery life than push FPS.
• "Auto" — whatever the driver picks when no preference is given. On laptops that often means LowPower; on desktops it usually means the only available adapter.

Adapter selection happens once, at startup. Calling SetPowerMode after the window opens stores the preference (so GetPowerMode returns it), but doesn't switch the live adapter. To actually change the adapter, call this before opening the window (or set it from a startup script the launcher runs).

Current power-mode preference. Default is "Quality".

Return one or more world-space AABBs covering a BasePart. Each entry is { Position, Size, Min, Max } with Position the AABB center and Size its full extents (max − min). Honors deformations, current animation state, and DynMesh-driven movement, so the boxes follow the live mesh.

quality controls how many boxes you get:

• 1 (default) — single box that encloses the entire part. Cheapest. Always accurate for cubes / spheres.
• 2+ — split a model's vertices into N bins along the longest axis and return a tight AABB per bin. Useful for long thin meshes where one big box is loose. Cubes and spheres always return one box regardless of quality.

Return every renderable BasePart whose bounds (computed at the given quality) overlap the AABB centered at center with full extents size. Skips parts with Render = false. Honors deformed / animated meshes and DynMesh offsets.

Return every part whose AABB intersects the sphere centered at center with the given radius. Filter is optional (BasePart) -> boolean; return true to keep, false / nil to drop.

Return every part whose AABB intersects the oriented box at center with full extents size, rotated by an Euler rotation (radians, defaults to no rotation). The GPU test is conservative (AABB-vs-OBB-AABB), so a heavily rotated thin box may include a few false positives near the corners. Tighten with the filter callback if you need exact OBB-OBB on a small candidate set.

Return every part whose AABB is inside or intersects the current camera's view frustum. Uses Renderable.Camera's CFrame, FOV, near and far plus the window's aspect ratio. Useful as a fast first pass for "what would be drawn this frame" or for area-of-interest streaming around the player.

Mesh-precise oriented-zone query. cframe places and rotates the zone, size is its full extents along the zone's local X / Y / Z. The compute shader tests each part's eight world-space corners against the zone OBB, and for parts with mesh data (Models) it additionally transforms the actual triangle vertices and tests each one, so a spike sticking out of a body still registers even when the body's bounding box doesn't reach the zone. Honors deformed meshes (uses the live deformed verts when DynMesh or animations are active, otherwise the source mesh). Also catches the inverse case where the zone is fully inside a large part.

Like the other Overlap queries this runs as one compute thread per part with an atomic-counter index list, then the CPU reads back only the matched indices.

Toggle the shadow term in the default 3D shader. Default false. Custom Frag3D shaders can read the same value via F.shadow_enabled (u32, 0 or 1) and choose to use it or ignore it.

Texture resolution future shadow maps will be rendered at. Clamped to [64, 8192] and rounded to the next power of two. Today the value also drives the strength of the stylized shadow floor in the default shader (higher = more contrasty receive-shadow darkening). Default 1024.

World-space radius (from the camera) beyond which the shadow term fades back to the regular half-Lambert. Set to 0 to disable distance fade. Default 80. Surfaced as F.shadow_distance in user shaders.

Depth comparison bias for future shadow-map sampling. Stored in the GPU module state and forwarded to the Frame uniform so user shaders can read it now. Default 0.0015.

Percentage-Closer-Filtering tap count, clamped to [1, 9]. 1 is hard shadows; 3 / 5 / 9 are progressively softer. Today this widens the smoothstep band of the default shader's stylized terminator; once real depth-map sampling lands the same value will drive the actual PCF kernel. Default 1.

Number of f32 slots. Same value as the size arg passed to GPU.NewBuffer; doesn't change after construction.

Write a list of f32 values into the buffer at offset (in floats, not bytes). Bounds-checked , writing past the end errors instead of corrupting adjacent GPU memory. Cheap; one queue-write under the hood.

Fill the entire buffer with one number. Convenience for clearing (:Fill(0)) or initialising to a sentinel.