---
title: "notices"
description: "The notices namespace — the engine's Luau API reference for notices."
section: "API Reference"
slug: "api-notices"
canonical: "https://origozero.ai/docs/api-notices"
updated: "2026-09-05T23:13:46.888826882+00:00"
tags: ["api", "reference"]
---

# notices

The `notices` namespace — 8 functions.

## globals/notices/post {#globals-notices-post}

```lua
notices.post(template: string, params: { [string]: any }?, opts: NoticeOpts?)
```

Post a notice. `template` is a fixed sentence used to collapse
repeats; put varying values in `params`. `opts.severity` defaults to
"info"; `opts.includeLocation` attaches the emitting call site.

**Parameters**

- `template` `string` — Fixed sentence identifying the notice.
- `params` `{ [string]: any }` _(optional)_ — Optional table of named values rendered alongside the template.
- `opts` `NoticeOpts` _(optional)_ — Optional table: severity ("info" | "warn" | "error"), includeLocation (boolean).

```lua
notices.post("wave complete", { wave = 3 })
notices.post("save slot corrupted, using defaults", { slot = id }, { severity = "warn" })
```

## modules/notices/README {#modules-notices-readme}

```lua
require("@builtin/modules/api/engine/notices") -- notices (also available as global 'notices')
```

Post an event record that surfaces to the operating agent on its next tool call. Public Luau surface over the `__notices_post` Internal FFI global.

Usage: local notices = require("@builtin/modules/api/engine/notices")
Also available as global: notices

## modules/notices/post {#modules-notices-post}

```lua
post(template: string, params: { [string]: any }?, opts: NoticeOpts?)
```

Post a notice. `template` is a fixed sentence used to collapse
repeats; put varying values in `params`. `opts.severity` defaults to
"info"; `opts.includeLocation` attaches the emitting call site.

**Parameters**

- `template` `string` — Fixed sentence identifying the notice.
- `params` `{ [string]: any }?` _(optional)_ — Optional table of named values rendered alongside the template.
- `opts` `NoticeOpts?` _(optional)_ — Optional table: severity ("info" | "warn" | "error"), includeLocation (boolean).

```lua
notices.post("wave complete", { wave = 3 })
notices.post("save slot corrupted, using defaults", { slot = id }, { severity = "warn" })
```

## tools/notices/drain {#tools-notices-drain}

```lua
notices.drain() -> Drained?
```

Take every pending notice and return the formatted delivery block — the same text that would otherwise be attached to your next tool result. DRAINING: what this returns is no longer queued, so read it. Returns nil when nothing is pending. For a caller that pulls its own context; if you read notices off your tool results, you do not need this. Overflow content is written to /source/tmp/notices/ and named in the block.

**Returns** `Drained?`

## tools/notices/list {#tools-notices-list}

```lua
notices.list() -> NoticesList
```

Show the currently pending notice keys and the suppressed set. Each pending row carries its key, template, severity, origin, count, and source; each suppressed row carries its key and the number of times it has fired while muted. Use a key from here with `suppress`.

**Returns** `NoticesList`

## tools/notices/suppress {#tools-notices-suppress}

```lua
notices.suppress(key: string) -> { suppressed: string }
```

Mute a notice key you have acknowledged. It keeps counting (visible in `list`) but never renders on a tool call again this session. Available to the operating agent; a loaded world component cannot mute its own notices.

**Parameters**

- `key` `string`

**Returns** `{ suppressed: string }`

```lua
"user:atlas:texture rebuilt"
```

## tools/notices/unsuppress {#tools-notices-unsuppress}

```lua
notices.unsuppress(key: string) -> { unsuppressed: string }
```

Un-mute a notice key you previously suppressed, so it renders on a tool call again. Available to the operating agent.

**Parameters**

- `key` `string`

**Returns** `{ unsuppressed: string }`

```lua
"user:atlas:texture rebuilt"
```

## typed/builtin//modules/api/engine/notices/notices/post {#typed-builtin-modules-api-engine-notices-notices-post}

```lua
notices.post(template: string, params: { [string]: any }?, opts: NoticeOpts?)
```

Post a notice. `template` is a fixed sentence used to collapse
repeats; put varying values in `params`. `opts.severity` defaults to
"info"; `opts.includeLocation` attaches the emitting call site.

**Parameters**

- `template` `string` — Fixed sentence identifying the notice.
- `params` `{ [string]: any }` _(optional)_ — Optional table of named values rendered alongside the template.
- `opts` `NoticeOpts` _(optional)_ — Optional table: severity ("info" | "warn" | "error"), includeLocation (boolean).

```lua
notices.post("wave complete", { wave = 3 })
notices.post("save slot corrupted, using defaults", { slot = id }, { severity = "warn" })
```