Skip to main content

Custom Beat Types

The beat system is extensible. You can register custom beat types alongside the five built-in ones (text, audio, animation, mood, camera).

Registration happens through the module system, using the same pattern the built-in beats use.

How registration works​

Each beat type is registered as a DialogueBeatTypeRegistration<TBeat> in the DialogueBeatCatalog. A single registration bundles everything the system needs to work with that beat type at both runtime and edit time.

The registration includes:

  • a display name for the editor
  • a runtime handler that presents the beat during playback
  • a duration calculator
  • a markdown codec for text-based serialization
  • an editor field factory for the Inspector UI

The registration pattern​

Beat types are registered in a module registrar using RegisterBeatType<T>(). The built-in beats are registered in DialogueModuleRegistrar.RegisterBuiltInDialogueBeats().

To register a custom beat type, create your own module registrar with an order higher than 200 (the dialogue registrar's order) and call the same registration method.

What you need to implement​

For a custom beat type, you need:

The beat class​

A class extending DialogueBeat. This holds the beat's serialized data.

IDialogueBeatRuntimeHandler​

Handles presenting the beat during playback. This is where you define what actually happens when the beat is encountered at runtime.

IDialogueBeatEditorDrawer​

Draws the beat's fields in the editor Inspector. This controls how the beat appears in the chat tree editor.

IDialogueBeatMarkdownCodec​

Serializes and deserializes the beat to and from markdown format. This is used by the markdown authoring system.

The beat catalog​

DialogueBeatCatalog (implementing IDialogueBeatCatalog) provides type-based lookups for registered beats. Given a beat type, it returns the appropriate runtime handler, editor drawer, or markdown codec.

The catalog validates at startup that every registered beat type has all required contracts. Missing contracts produce clear error messages.

Practical advice​

Before creating a custom beat type, check whether the existing types can achieve what you need. Mood beats can trigger arbitrary state changes, and animation beats can play any clip. Custom beat types are most useful when you need a fundamentally different presentation mechanism that does not map to any existing type.

When creating a custom beat, follow the pattern of the built-in text beat as a reference. It demonstrates all the required contracts in their simplest form.

Next step​

Continue to CIVIL-AI-SYSTEM Integration.

Last updated on