Skip to main content

Regions

Dry regions: tag a BasePart or Model OceanDry and there is no water inside its box. Where the box crosses the water line the surface is cut out of it at its walls, the underwater tint stays off for a camera inside, characters do not swim there and water events treat it as air. Submarine interiors, underwater rooms, diving bells.

A float inside a dry region gets no lift unless the region belongs to it (same model or welded assembly), so a submarine's hull floats while cargo inside it does not.

Types​

Box​

interface Box {
CFrame: CFrame
Half: Vector3--

half size

X: number
Z: number
Reach: number--

bounding radius in XZ

Bottom: number--

world Y

Top: number--

world Y

Instance: Instance--

the tagged part or model

Model: Model?--

the model it belongs to, if any

Owner: BasePart?--

the assembly it is welded into, if any

}

Outline​

interface Outline {
Planes: {number}--

per box, its four walls as inward normal x, z and offset (12 numbers)

Sinks: {number}--

per box, the height the surface inside it is drawn at, at most

Pieces: {number}--

the outline of all the boxes together: per segment its start x, z, its run x, z, 1 / length squared, length and box

MinX: number
MaxX: number
MinZ: number
MaxZ: number
}

Functions​

Refresh​

Regions.Refresh() → ()

Re-reads every OceanDry instance. Runs twice a second on its own.

Sync​

Regions.Sync() → ()

Moves every box to where its part is now. Cheap (a CFrame per box); runs every frame on its own, and the renderer calls it before drawing so the water is cut where the box is this frame.

List​

Regions.List() → {Box}

Every dry box.

Near​

Regions.Near(
x: number,
z: number,
radius: number
) → {Box}

Dry boxes whose footprint touches the circle (x, z, radius).

IsDry​

Regions.IsDry(point: Vector3) → boolean

True inside any dry box. Ocean:IsDry calls this.

IsDryFor​

Regions.IsDryFor(
point: Vector3,
instance: Instance
) → boolean

Like Regions.IsDry, but a box that belongs to instance (its own model or welded assembly) does not count.

CoversXZ​

Regions.CoversXZ(
box: Box,
x: number,
z: number,
margin: number?
) → boolean

True when (x, z) is within the box's footprint, grown by margin studs.

PushOut​

Regions.PushOut(
box: Box,
x: number,
z: number
) → (
number,--

x

number,--

z

boolean--

was inside

)

The nearest point on the box's footprint edge to (x, z), and whether the point was inside.

Outline​

Regions.Outline(
list: {Box},
level: number
) → Outline

The dry boxes in list cut through the horizontal plane at level (the water line), together: each box's footprint there, and the outline of all of them, less the walls one box hides inside another. Regions.Cut draws the surface against it.

Cut​

Regions.Cut(
outline: Outline,
x: number,
y: number,
z: number,
cell: number
) → (
number,--

x

number,--

y

number--

z

)

Where a point of a lattice surface (spacing cell) is drawn so that none of the surface is inside the outline's boxes. A point inside goes out to the nearest point of the outline and down under its box; a point outside within 2 cells goes onto the outline at its own height, and from there to 3.5 cells out eases back to where it was. Near a corner of the outline, points on it slide into the corner. So every triangle that crosses the outline has its corners on one wall: the water meets the wall at the water line and hangs straight down it, with none inside and no dip outside. Continuous in the point and the boxes, so a moving box cuts smoothly.

Show raw api
{
    "functions": [
        {
            "name": "Refresh",
            "desc": "Re-reads every `OceanDry` instance. Runs twice a second on its own.",
            "params": [],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 84,
                "path": "src/Ocean/Regions.luau"
            }
        },
        {
            "name": "Sync",
            "desc": "Moves every box to where its part is now. Cheap (a CFrame per box); runs every frame on its own,\nand the renderer calls it before drawing so the water is cut where the box is this frame.",
            "params": [],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 120,
                "path": "src/Ocean/Regions.luau"
            }
        },
        {
            "name": "List",
            "desc": "Every dry box.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ Box }"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 134,
                "path": "src/Ocean/Regions.luau"
            }
        },
        {
            "name": "Near",
            "desc": "Dry boxes whose footprint touches the circle `(x, z, radius)`.",
            "params": [
                {
                    "name": "x",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "z",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "radius",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ Box }"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 147,
                "path": "src/Ocean/Regions.luau"
            }
        },
        {
            "name": "IsDry",
            "desc": "True inside any dry box. [Ocean:IsDry] calls this.",
            "params": [
                {
                    "name": "point",
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 171,
                "path": "src/Ocean/Regions.luau"
            }
        },
        {
            "name": "IsDryFor",
            "desc": "Like [Regions.IsDry], but a box that belongs to `instance` (its own model or welded assembly) does not count.",
            "params": [
                {
                    "name": "point",
                    "desc": "",
                    "lua_type": "Vector3"
                },
                {
                    "name": "instance",
                    "desc": "",
                    "lua_type": "Instance"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 200,
                "path": "src/Ocean/Regions.luau"
            }
        },
        {
            "name": "CoversXZ",
            "desc": "True when `(x, z)` is within the box's footprint, grown by `margin` studs.",
            "params": [
                {
                    "name": "box",
                    "desc": "",
                    "lua_type": "Box"
                },
                {
                    "name": "x",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "z",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "margin",
                    "desc": "",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 219,
                "path": "src/Ocean/Regions.luau"
            }
        },
        {
            "name": "PushOut",
            "desc": "The nearest point on the box's footprint edge to `(x, z)`, and whether the point was inside.",
            "params": [
                {
                    "name": "box",
                    "desc": "",
                    "lua_type": "Box"
                },
                {
                    "name": "x",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "z",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "x",
                    "lua_type": "number"
                },
                {
                    "desc": "z",
                    "lua_type": "number"
                },
                {
                    "desc": "was inside",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 236,
                "path": "src/Ocean/Regions.luau"
            }
        },
        {
            "name": "Outline",
            "desc": "The dry boxes in `list` cut through the horizontal plane at `level` (the water line), together:\neach box's footprint there, and the outline of all of them, less the walls one box hides inside\nanother. [Regions.Cut] draws the surface against it.",
            "params": [
                {
                    "name": "list",
                    "desc": "",
                    "lua_type": "{ Box }"
                },
                {
                    "name": "level",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Outline"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 298,
                "path": "src/Ocean/Regions.luau"
            }
        },
        {
            "name": "Cut",
            "desc": "Where a point of a lattice surface (spacing `cell`) is drawn so that none of the surface is inside\nthe outline's boxes. A point inside goes out to the nearest point of the outline and down under\nits box; a point outside within 2 cells goes onto the outline at its own height, and from there\nto 3.5 cells out eases back to where it was. Near a corner of the outline, points on it slide\ninto the corner. So every triangle that crosses the outline has its corners on one wall: the\nwater meets the wall at the water line and hangs straight down it, with none inside and no dip\noutside. Continuous in the point and the boxes, so a moving box cuts smoothly.",
            "params": [
                {
                    "name": "outline",
                    "desc": "",
                    "lua_type": "Outline"
                },
                {
                    "name": "x",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "y",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "z",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "cell",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "x",
                    "lua_type": "number"
                },
                {
                    "desc": "y",
                    "lua_type": "number"
                },
                {
                    "desc": "z",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 408,
                "path": "src/Ocean/Regions.luau"
            }
        },
        {
            "name": "Init",
            "desc": "",
            "params": [],
            "returns": [],
            "function_type": "static",
            "private": true,
            "source": {
                "line": 473,
                "path": "src/Ocean/Regions.luau"
            }
        },
        {
            "name": "Stop",
            "desc": "",
            "params": [],
            "returns": [],
            "function_type": "static",
            "private": true,
            "source": {
                "line": 493,
                "path": "src/Ocean/Regions.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "Box",
            "desc": "",
            "fields": [
                {
                    "name": "CFrame",
                    "lua_type": "CFrame",
                    "desc": ""
                },
                {
                    "name": "Half",
                    "lua_type": "Vector3",
                    "desc": "half size"
                },
                {
                    "name": "X",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "Z",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "Reach",
                    "lua_type": "number",
                    "desc": "bounding radius in XZ"
                },
                {
                    "name": "Bottom",
                    "lua_type": "number",
                    "desc": "world Y"
                },
                {
                    "name": "Top",
                    "lua_type": "number",
                    "desc": "world Y"
                },
                {
                    "name": "Instance",
                    "lua_type": "Instance",
                    "desc": "the tagged part or model"
                },
                {
                    "name": "Model",
                    "lua_type": "Model?",
                    "desc": "the model it belongs to, if any"
                },
                {
                    "name": "Owner",
                    "lua_type": "BasePart?",
                    "desc": "the assembly it is welded into, if any"
                }
            ],
            "source": {
                "line": 42,
                "path": "src/Ocean/Regions.luau"
            }
        },
        {
            "name": "Outline",
            "desc": "",
            "fields": [
                {
                    "name": "Planes",
                    "lua_type": "{ number }",
                    "desc": "per box, its four walls as inward normal x, z and offset (12 numbers)"
                },
                {
                    "name": "Sinks",
                    "lua_type": "{ number }",
                    "desc": "per box, the height the surface inside it is drawn at, at most"
                },
                {
                    "name": "Pieces",
                    "lua_type": "{ number }",
                    "desc": "the outline of all the boxes together: per segment its start x, z, its run x, z, 1 / length squared, length and box"
                },
                {
                    "name": "MinX",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "MaxX",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "MinZ",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "MaxZ",
                    "lua_type": "number",
                    "desc": ""
                }
            ],
            "source": {
                "line": 279,
                "path": "src/Ocean/Regions.luau"
            }
        }
    ],
    "name": "Regions",
    "desc": "Dry regions: tag a BasePart or Model `OceanDry` and there is no water inside its box. Where the box\ncrosses the water line the surface is cut out of it at its walls, the underwater tint stays off for a camera inside, characters do not swim there and\nwater events treat it as air. Submarine interiors, underwater rooms, diving bells.\n\nA float inside a dry region gets no lift unless the region belongs to it (same model or welded\nassembly), so a submarine's hull floats while cargo inside it does not.",
    "source": {
        "line": 28,
        "path": "src/Ocean/Regions.luau"
    }
}