This function creates a collision sphere. This is a shape that has a position and a radius. See Wikipedia for a definition of a sphere.

Tip

To visualize a colshape when writing scripts, use the client console command showcol.

OOP Syntax Help! I don't understand this!

• Method:ColShape.Sphere(...)

Syntax

colshape|false createColSphere ( float fX, float fY, float fZ, float fRadius )

Required Arguments

• fX: The collision sphere's center point's X axis position.
• fY: The collision sphere's center point's Y axis position.
• fZ: The collision sphere's center point's Z axis position.
• fRadius: The collision sphere's radius.

Returns

• colshape|false: col-sphere

Returns a colshape element if successful, false if invalid arguments were passed to the function.

Code Examples

Example 1 Example 2 (OOP) Example 3

server

Example 1:This example displays a chat message when a player enters the colshape and allows the colshape to be created using a console command set_zone.

local theZone

local function shapeHit(hitElement, matchingDimensions)
    if (hitElement and getElementType(hitElement) == 'player' and matchingDimensions) then
        outputChatBox(getPlayerName(thePlayer).. " is in the zone!")
    end
end

function setZone(playerSource, commandName, fX, fY, fZ, fRadius)
    local fX, fY, fZ, fRadius = tonumber(fX), tonumber(fY), tonumber(fZ), tonumber(fRadius)
    if (not fX) or (not fY) or (not fZ) or (not fRadius) then
        outputChatBox("Syntax: /"..commandName.." [X] [Y] [Z] [Radius]", playerSource)
    else
        if (theZone) then
            destroyElement(theZone)
        end
        local tempCol = createColSphere(fX, fY, fZ, fRadius)
        addEventHandler("onColShapeHit", tempCol, shapeHit)
        outputChatBox("Zone has "..(theZone ~= nil and "moved" or "created").."!", playerSource)
        theZone = tempCol
    end
end
addCommandHandler("set_zone", setZone, false, false)

server

OOP Required

Example 1:This example displays a chat message when a player enters the colshape and allows the colshape to be created using a console command set_zone.

local theZone

local function shapeHit(hitElement, matchingDimensions)
    if (hitElement and element.type == 'player' and matchingDimensions) then
        outputChatBox(thePlayer.name.. " is in the zone!")
    end
end

function setZone(playerSource, commandName, fX, fY, fZ, fRadius)
    local fX, fY, fZ, fRadius = tonumber(fX), tonumber(fY), tonumber(fZ), tonumber(fRadius)
    if (not fX) or (not fY) or (not fZ) or (not fRadius) then
        playerSource:outputChat("Syntax: /"..commandName.." [X] [Y] [Z] [Radius]")
    else
        if (theZone) then
            theZone:destroy()
        end
        local tempCol = ColShape.Sphere(fX, fY, fZ, fRadius)
        addEventHandler("onColShapeHit", tempCol, shapeHit)
        playerSource:outputChat("Zone has "..(theZone ~= nil and "moved" or "created").."!")
        theZone = tempCol
    end
end
addCommandHandler("set_zone", setZone, false, false)

server

This example allows creation of claymores, which trigger and explode.

function createClaymore(x, y, z, creator)
    local x, y, z = getElementPosition(creator)
    local claymoreObject = createObject(1945, x, y, z - 1, 0, 0, 90) -- create an object which looks like a claymore
    local claymoreCol = createColSphere(x, y, z, 1) -- create a col sphere with radius 1
    setElementData(claymoreCol, "type", "claymore") -- store the type of colshape so it can be retrieved
    setElementData(claymoreCol, "object", claymoreObject) -- store the object of the claymore
    setElementData(claymoreCol, "creatorPlayer", creator) -- store the person who created it
end

function claymoreHit(player, matchingDimension)
    if getElementData(source, "type") == "claymore" then -- ensure its a claymore
        -- retrieve the object associated to the claymore, and who created it
        local claymoreObject = getElementData(source, "object")
        local claymoreCreator = getElementData(source, "creatorPlayer")
        -- get the position of the claymore
        local x, y, z = getElementPosition(source)
        createExplosion(x, y, z, 12, claymoreCreator) -- create an explosion, associated to the creator, of a small size at the col's position
        -- destroy the claymore object, and the col shape so it doesnt trigger again.
        destroyElement(claymoreObject)
        destroyElement(source)
    end
end
addEventHandler("onColShapeHit", getRootElement(), claymoreHit)

Gallery

Click on the image to view the full preview along with the description.

See Also

Colshape Functions

• addColPolygonPoint
• createColCircle
• createColCuboid
• createColPolygon
• createColRectangle
• createColSphere
• createColTube
• getColPolygonHeight
• getColPolygonPointPosition
• getColPolygonPoints
• getColShapeRadius
• getColShapeSize
• getColShapeType
• isInsideColShape
• removeColPolygonPoint
• setColPolygonHeight
• setColPolygonPointPosition
• setColShapeRadius
• setColShapeSize

Colshape Events

• onClientColShapeHit
• onClientColShapeLeave
• onColShapeHit
• onColShapeLeave

Reference

• Scripting Functions