> For the complete documentation index, see [llms.txt](https://docs.anvil.team/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.anvil.team/namespaces/engine.md).

# engine

### Methods 

* [addEventListener](#engine.addeventlistener-name-callable)
* [removeEventListener](#engine.removeeventlistener-name)
* [removeAllEventListeners](#engine.removealleventlisteners)
* [getServerName](#engine.getservername)
* [getPlayerState](#engine.getplayerstate)
* [getRefDef](#engine.getrefdef)
* [getCG](#engine.getcg)
* [getDvar](#engine.getdvar-dvarname)
* [getUserCmd](#engine.getusercmd)
* [getPreviousUserCmd](#engine.getusercmd-1)
* [execCommand](#engine.execcommand-command)
* [getPlayerList](#engine.getplayerlist)
* [getLocalClientEntity](#engine.getclosestplayer)
* [getClosestPlayer](#engine.getclosestplayer)
* [isVisible](#engine.isvisible-end)
* [getBoneOrigin](#engine.getheadorigin-cliententity)
* [trace](#engine.trace-start-end)
* [getForwardVector](#engine.trace-start-end-1)
* [angle2short](#engine.angle2short-angle)
* [short2angle](#engine.short2angle-short)
* [getWindowSize](#engine.getwindowsize)
* [notify](#engine.notify-message)
* [disconnect](#engine.disconnect)
* [setStat](#engine.setstat-id-value)
* [getScriptId](#engine.getscriptid)

### <mark style="color:green;">`engine.addEventListener(name, callable)`</mark>

* <mark style="color:purple;">`event`</mark> - The type of event you want to listen for
* <mark style="color:purple;">`callable`</mark> - A defined function or a lambda

This method registers a eventlistener for the specified event, that is a function that will be executed **every time** the event occurs.

**Example:**

```lua
function hi()
    print("whats up")
end

engine.addEventListener("render", hi);
```

This will print `whats up` every time a new frame is rendered.

#### Available Events

* <mark style="color:purple;">`render`</mark> - Emitted when a new frame is being rendered
* <mark style="color:purple;">`onBeforeEndScene`</mark> - Emitted right before a new frame is being rendered
* <mark style="color:purple;">`onAfterEndScene`</mark> - Emitted after a new frame has been rendered
* <mark style="color:purple;">`onBeforeCL_WritePacket`</mark> - Emitted right before the game sends a packet to the server
* <mark style="color:purple;">`onAfterCL_CreateNewCommands`</mark> - Emitted after a new user command has been created
* <mark style="color:purple;">`onLoad`</mark> - Emitted when you load your position
* <mark style="color:purple;">`onSave`</mark> - Emitted when you save your position
* <mark style="color:purple;">`onBounce`</mark> - Emitted when you bounce

### <mark style="color:green;">`engine.removeEventListener(name)`</mark>

* <mark style="color:purple;">`event`</mark> - The name of the event you dont want to listen/react to anymore

Removes a previously attachted event listener by the name of the event.

**Example:**

```lua
engine.removeEventListener("render")
```

### <mark style="color:green;">`engine.removeAllEventListeners()`</mark>

Removes all attached event listeners for the current script.

**Example:**

```lua
engine.removeAllEventListeners()
```

### <mark style="color:green;">`engine.getServerName()`</mark>

Returns the name of the server you're currently connected to.

**Example:**

```lua
--Suppose you play on 3xP
local name = engine.getServerName()
print(name) -- 3xP' Codjumper
```

### <mark style="color:green;">`engine.getPlayerState()`</mark>

Returns the predicted [playerState](/types/playerstate.md).&#x20;

**Example:**

```lua
local playerState = engine.getPlayerState()
print(playerState.Origin.x)
```

### <mark style="color:green;">`engine.getRefDef()`</mark>

Returns the [refDef](/types/refdef.md) object.

**Example:**

```lua
local refdef = engine.getRefDef()
print(refdef.width) -- CoD4 window width
```

### <mark style="color:green;">`engine.getCG()`</mark>

Returns the [cg](/types/cg.md) object.

**Example:**

```lua
local cg = engine.getCG()
print(cg.ClientNum) -- Your client number
```

### <mark style="color:green;">`engine.getDvar(dvarName)`</mark>

Returns the [dvar](/types/dvar.md) you requested. You can then change the values of the dvar with [methods](/types/dvar.md).

**Example:**

```lua
local sens = engine.getDvar("sensitivity")
sens:setFloat(1.5) -- sets sensitivity to 1.5
```

### <mark style="color:green;">`engine.getUserCmd()`</mark>

Returns the latest [user command](/types/usercmd.md).

**Example:**

```lua
local usercmd = engine.getUserCmd();
usercmd:jump(); -- Makes you jump
usercmd:shoot(); -- Shoots your weapon once
```

### <mark style="color:green;">`engine.getPreviousUserCmd()`</mark>

Returns the previous [user command](/types/usercmd.md). Use previous user cmd's for silent stuff.

**Example:**

```lua
local usercmd = engine.getPreviousUserCmd();
usercmd:jump(); -- Makes you jump
usercmd:shoot(); -- Shoots your weapon once
```

### <mark style="color:green;">`engine.execCommand(command)`</mark>

* <mark style="color:purple;">`command`</mark> - A console command to execute

Executes the given command

**Example:**

```lua
engine.execCommand("say hi from lua");
```

### <mark style="color:green;">`engine.getPlayerList()`</mark>

Returns a list of players in the server as a list of [clientEntity](/types/cliententity.md)'s

**Example:**

```lua
local players = engine.getPlayerList()

-- Print the position of all players right now
for i, entity in ipairs(players) do
    print(entity.origin:toString())
end
```

### <mark style="color:green;">`engine.getLocalClientEntity()`</mark>

Returns the [clientEntity ](/types/cliententity.md)for yourself.

**Example:**

```lua
local me = engine.getLocalClientEntity()

-- Prints your team
print("I am in team " .. tostring(me.team))
```

### <mark style="color:green;">`engine.getClosestPlayer()`</mark>

Returns the closest player as a [clientEntity](/types/cliententity.md)

**Example:**

```lua
local closestPlayer = engine.getClosestPlayer()

-- Makes you look at the closest player
player.lookAtPosition(closestPlayer.origin)
```

### <mark style="color:green;">`engine.isVisible(target)`</mark>

* <mark style="color:purple;">`target`</mark> - The position as a [Vec3](/types/vec3.md) to check if it is visible

Returns true if target is visible from your currnent position, false otherwise.

**Example:**

```lua
-- True if the map origin is visible from your current position
engine.isVisible(Vec3:new(0, 0, 0))

-- True if you can see the closest player
engine.isVisible(engine.getClosestPlayer())
```

### <mark style="color:green;">`engine.trace(start, end)`</mark>

Performs a ray trace from start to end and returns a [trace](/types/trace.md) object.

**Example:**

```lua
local pointA = Vec3:new(0, 0, 0)
local pointB = Vec3:new(500, 500, 1000)

local trace = engine.trace(pointA, pointB)
print("Hit something at: " .. trace.getHitLocation(pointA, pointB))
```

### <mark style="color:green;">`engine.getForwardVector(viewangles)`</mark>

Obtain the forward vector as a [Vec3](/types/vec3.md) from the given viewangles as a [Vec3](/types/vec3.md)

**Example:**

```lua
local forward = engine.getForwardVector(player.getView())
print("Forward: " .. forward:toString())
```

### <mark style="color:green;">`engine.angle2short(angle)`</mark>

Converts the decimal angle to a 2 byte integer representation.

{% hint style="info" %}
A unsigned 2 byte integer has a range from 0 to 65535.\
CoD4 is based on the Quake engine. Back in the 90's they optimized the bandwidth needed to communicate with the server.\
Instead of sending your viewangles as 3 floats (12 byte), they're sent as 2 byte shorts each, reducing the bandwidth by 50%.\
If you're working with usercmd's then please be aware that the viewangles there are in the short representation.\
\
Things to consider:\
Since a full circle of 360 degrees are mapped onto a finite interval of 0 - 65535,\
the precision suffers. The minimum change of a viewangle is:

<mark style="color:green;">360.0</mark> / <mark style="color:green;">65536</mark> = <mark style="color:green;">0.0054931640625</mark>
{% endhint %}

**Example:**&#x20;

```lua
-- Prints 16384
print("90 degree as short: " .. tostring(engine.angle2short(90.0)))
```

### <mark style="color:green;">`engine.short2angle(short)`</mark>

Converts a 2 byte integer representation of an angle back to a float.

**Example:**&#x20;

```lua
-- Prints 90.0
print("16384 as angle: " .. tostring(engine.short2angle(16384)))
```

### <mark style="color:green;">`engine.getWindowSize()`</mark>

Returns the CoD4 window size as a [Vec2](/types/vec2.md)

**Example:**&#x20;

```lua
-- Prints your window dimensions
print("Window dimensions: " .. engine.getWindowSize():toString())
```

### <mark style="color:green;">`engine.notify(message)`</mark>

Displays a notification on the right hand side of the screen with the given message.

**Example:**&#x20;

```lua
-- Display notification
engine.notify("Test toast")
```

### <mark style="color:green;">`engine.disconnect()`</mark>

Disconnect from current server.

**Example:**&#x20;

```lua
-- Disconnects
engine.disconnect()
```

### <mark style="color:green;">`engine.setStat(id, value)`</mark>

Sets a stat id to a given value (Equivalent of GSC player setStat).

<mark style="color:purple;">`id`</mark>- The id of the stat

<mark style="color:purple;">`value`</mark>- The value you wish to set

**Example:**&#x20;

```lua
-- Set ruby currency on Vistic CodJumper 
engine.setStat(2392, 99999)
```

### <mark style="color:green;">`engine.isVisible(target)`</mark>

* <mark style="color:purple;">`target`</mark> - The position as a [Vec3](/types/vec3.md) to check if it is visible

Returns true if target is visible from your currnent position, false otherwise.

**Example:**

```lua
-- True if the map origin is visible from your current position
engine.isVisible(Vec3:new(0, 0, 0))

-- True if you can see the closest player
engine.isVisible(engine.getClosestPlayer())
```

### <mark style="color:green;">`engine.getScriptId()`</mark>

Returns the id of the current script. Use this to uniquely identify your script.\
Useful for ImGui Window ID's etc.

**Example:**

```lua
print("script id: " .. engine.getScriptId())
```