# CyberM.vfx — client runtime

Runs inside the game process. Reads and presentation are local; anything that changes shared state has to go through the server.

6 functions.

## catalog

```lua
CyberM.vfx.catalog()
```

`GAME` — Requires a live game instance.

Returns the curated stable world-VFX aliases and cooked paths.

Catalog access does not start an effect. Raw cooked paths remain build-dependent even when present.

Returns: `table mapping alias to effect path, or nil`, `reason`

Registered in `ResourceHost.cpp` (line 6814) as `LuaVfxCatalog`.

## clear

```lua
CyberM.vfx.clear()
```

`GAME` — Requires a live game instance.

Stops every VFX owned by the calling resource.

Requires `world.effects`; SFX and other resource owners are unaffected.

Returns: `true on success, otherwise false`, `reason`

Registered in `ResourceHost.cpp` (line 6809) as `LuaEffectClear`.

## list

```lua
CyberM.vfx.list()
```

`GAME` — Requires a live game instance.

Lists active VFX owned by the calling resource.

Requires `world.effects`.

Returns: `array of { id, kind, name, entity, remaining }, or nil`, `reason`

Registered in `ResourceHost.cpp` (line 6812) as `LuaEffectList`.

## play

```lua
CyberM.vfx.play(effect, options)
```

`GAME` — Requires a live game instance.

Starts a resource-owned world VFX at a fixed transform.

Requires `world.effects`. `options` requires `position` and accepts `orientation`, `duration`, and `ignoreTimeDilation`. The effect is released automatically with its owner.

| Parameter | Type | Required | Default |
|---|---|---|---|
| `effect` | `string` | required | — |
| `options` | `table` | required | — |

Returns: `effect handle string, or nil`, `reason`

Registered in `ResourceHost.cpp` (line 6805) as `LuaVfxPlay`.

## playEntity

```lua
CyberM.vfx.playEntity(effect, [options])
```

`GAME` — Requires a live game instance.

Starts a resource-owned authored VFX on an entity.

Requires `world.effects`. Options accept `entity`, `instance`, `persistOnDetach`, `breakAllLoops`, `breakAllOnDestroy`, and `duration`; omitting `entity` targets the local player.

| Parameter | Type | Required | Default |
|---|---|---|---|
| `effect` | `string` | required | — |
| `options` | `table` | optional | — |

Returns: `effect handle string, or nil`, `reason`

Registered in `ResourceHost.cpp` (line 6806) as `LuaVfxPlayEntity`.

## stop

```lua
CyberM.vfx.stop(id)
```

`GAME` — Requires a live game instance.

Stops one VFX handle owned by the calling resource.

Requires `world.effects`.

| Parameter | Type | Required | Default |
|---|---|---|---|
| `id` | `string` | required | — |

Returns: `true on success, otherwise false`, `reason`

Registered in `ResourceHost.cpp` (line 6807) as `LuaEffectStop`.