# 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())
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.anvil.team/namespaces/engine.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.