#Event naming

This document explains the canonical event-name format used across the Indigauge Rust SDK and the ig_* macros. It matches the runtime and compile-time validation implemented in indigauge-core so names used in your game will be accepted by the SDK and by the ig_* macros.

#Format (required)

• Shape: namespace.event (exactly one .)
• Characters: ASCII letters only on each side (A–Z, a–z)
• Length: at least 3 characters in total; . cannot be first or last

Examples:

player.jump        # valid
ui.click           # valid
game.start         # valid

Invalid examples (reason in comments):

game               # missing '.'
.start             # '.' is first
game.              # '.' is last
game..start        # multiple '.'
game_1.start       # '_' and digits are not allowed
game.1start        # digits are not allowed

#Why these rules?

• The SDK performs a simple, fast validation (compile-time for string literals) to ensure event names are predictable and easy to index in the backend.
• Keep event types short and stable — use metadata for variable information.

#Compile-time validation

• The ig_* macros (eg. ig_info!, ig_warn!) validate event_type at compile time when you provide a string literal or const string.
• If the value does not meet the rules above the macro will fail to compile (you'll get a clear error).

Example — compile-time checked:

ig_info!("game.start");
const PLAYER_JUMP: &str = "player.jump";
ig_info!(PLAYER_JUMP, { "height": 2.4 });

Note: passing a runtime String (non-const) to the macro will not satisfy compile-time validation and will not compile.

#Macros and levels

• ig_trace!(...) — trace-level
• ig_debug!(...) — debug-level
• ig_info!(...) — info-level
• ig_warn!(...) — warn-level
• ig_error!(...) — error-level

All macros accept an optional inline JSON-like metadata object:

ig_info!("ui.click", { "button": "play", "x": 128, "y": 256 });

#Recommended naming conventions

• Use a short noun for namespace (domain area): ui, player, game, network, save.
• Use a verb or noun-verb for event: click, jump, start, failed.
• Prefer lowercase and stable, non-ephemeral names.
• Put variable or contextual data in metadata, not in the event name.

Good:

• ui.click
• player.jump
• session.start

Avoid:

• Encoding IDs or timestamps into the event type (use metadata instead)
• Adding implementation detail to the event type

#Using constants

Defining event-type consts reduces typos and keeps values discoverable:

const HIT_BRICK: &str = "hit.brick";
ig_info!(HIT_BRICK);

Because the macros perform compile-time validation, const or literal strings are the recommended approach for re-use.

#Tracing integration

When the tracing feature is enabled the tracing layer will forward structured log events that carry an ig field to Indigauge. Example:

info!(ig = "counter.increase", value = counter_value);

Use the same namespace.event naming rules for the ig field.

#Integration notes

• The ig_* macros dispatch events through a pluggable dispatcher (the host crate must register one via set_event_dispatcher). The Bevy plugin does this automatically when enabled.
• Events are queued and flushed by the host integration; calling a macro is cheap and safe even when no active session or dispatcher exists.

#Quick checklist

• Use namespace.event (exactly one dot)
• Use only letters (A–Z/a–z)
• Prefer literals or const values (compile-time validation)
• Put dynamic data in metadata, not in the event name

References

• validate_event_type_compile_time (compile-time check in indigauge-core)
• ig_info!, ig_warn!, ig_error! (event macros)