# Script

**Namespace:** `dmScript`
**Language:** C++
**Type:** Defold C++
**File:** `script.h`
**Source:** `engine/gamesys/src/dmsdk/gamesys/script.h`
**Include:** `dmsdk/gamesys/script.h`

Built-in scripting functions.

## API

### CheckCollection
*Type:* FUNCTION
Get current gameobject's collection handle

**Notes**

- Works from both a .script/.gui_script

**Parameters**

- `L` (lua_State*) - lua state
- `index` (int) - lua-arg

**Returns**

- `instance` (lua_State*) - gameobject instance

### CheckGOInstance
*Type:* FUNCTION
Get current game object instance
Works in both gameobjects and gui scripts

**Parameters**

- `L` (lua_State*) - lua state

**Returns**

- `instance` (dmGameObject::HInstance)

### CheckGOInstance
*Type:* FUNCTION
Get gameobject instance
The instance reference (url) at stack index "index" will be resolved to an instance.

**Notes**

- The function only accepts instances in "this" collection. Otherwise a lua-error will be raised.

**Parameters**

- `L` (lua_State*) - lua state
- `index` (int) - lua-arg

**Returns**

- `instance` (dmGameObject::HInstance) - gameobject instance

**Examples**

How to get the position of a gameobject in a script extension
```
static int get_position(lua_State* L)
{
    DM_LUA_STACK_CHECK(L, 3);
    dmGameObject::HInstance instance = dmScript::CheckGOInstance(L, 1);
    dmVMath::Point3 position = dmGameObject::GetPosition(instance);
    lua_pushnumber(L, position.getX());
    lua_pushnumber(L, position.getY());
    lua_pushnumber(L, position.getZ());
    return 3;
}

```

### dmScript::CheckBuffer
*Type:* FUNCTION
Retrieve a LuaHBuffer from the supplied lua state.
Check if the value in the supplied index on the lua stack is a LuaHBuffer and returns it.

**Notes**

- The dmBuffer::IsBufferValid is already called on the returned buffer

**Parameters**

- `L` (lua_State*) - lua state
- `index` (int) - Index of the value

**Returns**

- `buffer` (LuaHBuffer*) - pointer to dmScript::LuaHBuffer

### dmScript::CheckBufferNoError
*Type:* FUNCTION
Retrieve a LuaHBuffer from the supplied lua state.
Check if the value in the supplied index on the lua stack is a LuaHBuffer and returns it.

**Notes**

- Returns 0 on error. Does not invoke lua_error.
- deprecated. Prefer ToBuffer() instead.
- The dmBuffer::IsBufferValid is already called on the returned buffer

**Parameters**

- `L` (lua_State*) - lua state
- `index` (int) - Index of the value

**Returns**

- `buffer` (LuaHBuffer*) - pointer to dmScript::LuaHBuffer or 0 if not valid

### dmScript::CheckBufferUnpack
*Type:* FUNCTION
Retrieve a HBuffer from the supplied lua state
Check if the value in the supplied index on the lua stack is a LuaHBuffer and it's valid, returns the HBuffer.

**Notes**

- The dmBuffer::IsBufferValid is already called on the returned buffer

**Parameters**

- `L` (lua_State*) - lua state
- `index` (int) - Index of the value

**Returns**

- `buffer` (dmBuffer::HBuffer) - buffer if valid, 0 otherwise

### dmScript::CheckBufferUnpackNoError
*Type:* FUNCTION
Retrieve a HBuffer from the supplied lua state
Check if the value in the supplied index on the lua stack is a LuaHBuffer and it's valid, returns the HBuffer.

**Notes**

- The dmBuffer::IsBufferValid is already called on the returned buffer

**Parameters**

- `L` (lua_State*) - lua state
- `index` (int) - Index of the value

**Returns**

- `buffer` (dmBuffer::HBuffer) - buffer if valid, 0 otherwise

### dmScript::IsBuffer
*Type:* FUNCTION
Check if the value is a dmScript::LuaHBuffer

**Parameters**

- `L` (lua_State*) - lua state
- `index` (int) - Index of the value

**Returns**

- `boolean` (boolean) - True if value at index is a LuaHBuffer

### dmScript::LuaHBuffer
*Type:* STRUCT
Holds info about the buffer and who owns it.

**Members**

- `Union` - of
    - m_BufferRes [type:void*]                       A buffer resource
    - m_Buffer    [type:dmBuffer::HBuffer]           A buffer
- `m_Buffer` (dmBuffer::HBuffer) - The buffer (or resource)
- `m_Owner` (dmScript::LuaBufferOwnership) - What ownership the pointer has

**Examples**

See examples for dmScript::PushBuffer()

### dmScript::PushBuffer
*Type:* FUNCTION
Will increase the stack by 1.

**Parameters**

- `L` (lua_State*) - lua state
- `buffer` (dmScript::LuaHBuffer) - buffer to push

**Examples**

How to push a buffer and give Lua ownership of the buffer (GC)
```
dmScript::LuaHBuffer luabuf(buffer, dmScript::OWNER_LUA);
PushBuffer(L, luabuf);

```

How to push a buffer and keep ownership in C++
```
dmScript::LuaHBuffer luabuf(buffer, dmScript::OWNER_C);
PushBuffer(L, luabuf);

```

### dmScript::ToBuffer
*Type:* FUNCTION
Retrieve a LuaHBuffer from the supplied lua state.
Check if the value in the supplied index on the lua stack is a LuaHBuffer and returns it.

**Notes**

- Returns 0 on error. Does not invoke lua_error.
- The dmBuffer::IsBufferValid is already called on the returned buffer

**Parameters**

- `L` (lua_State*) - lua state
- `index` (int) - Index of the value

**Returns**

- `buffer` (LuaHBuffer*) - pointer to dmScript::LuaHBuffer or 0 if not valid

### GetComponentFromLua
*Type:* FUNCTION
Get component user data from a url.

**Notes**

- The object referenced by the url must be in the same collection as the caller.

**Parameters**

- `L` (lua_State*) - Lua state
- `index` (int) - index to argument (a url)
- `component_type` (const char*) - E.g. "factoryc". The call will fail if the found component does not have the specified extension
- `world` (dmGameObject::HComponentWorld*) - The world associated owning the component. May be 0
- `component` (dmGameObject::HComponent*) - The component data associated with the url. May be 0
- `url` (dmMessage::URL*) - The resolved url. May be 0

### LuaBufferOwnership
*Type:* ENUM
Buffer ownership.
 - OWNER_C   - m_Buffer is owned by C side, should not be destroyed when GCed
 - OWNER_LUA - m_Buffer is owned by Lua side, will be destroyed when GCed
 - OWNER_RES - m_Buffer not used, has a reference to a buffer resource instead. m_BufferRes is owned by C side, will be released when GCed

**Members**

- `dmScript::OWNER_C`
- `dmScript::OWNER_LUA`
- `dmScript::OWNER_RES`