#Getting started with Godot

This guide explains how to install and use the official Indigauge Godot addon in a Godot 4 project.

The addon gives you session tracking, structured event logging, session metadata, heartbeats, and an in-game feedback panel with optional screenshot upload.

For a complete playable reference, open the example project in godot-addon/example/.

#Requirements

• Godot 4.x
• An Indigauge project public key
• The addon files from godot-addon/

Use the public key for the game you want to track. The key is safe to ship in a client build because it only identifies the game for ingest.

#Install the addon

Copy the addon into your Godot project under addons/indigauge/:

your_project/
  addons/
    indigauge/
      plugin.cfg
      client.gd
      core.gd
      types.gd
      feedback_panel.gd
      feedback_panel.tscn

Then enable it in Godot:

1. Open Project > Project Settings > Plugins.
2. Enable Indigauge.
3. Add an IndigaugeClient node to your main scene, or register the client as an autoload.

#Choose an integration style

There are three common ways to start Indigauge. Use the scene-node setup when you want the client to live beside the rest of your game scene. Use an autoload when you want global access from many scripts. Use Inspector setup for a low-code startup path.

#Scene node setup

Add a Node to your main scene, attach res://addons/indigauge/client.gd, and start the session from your scene script:

@onready var indigauge: IndigaugeClient = $IndigaugeClient

func _ready() -> void:
	indigauge.session_started.connect(_on_indigauge_session_started)
	indigauge.session_failed.connect(_on_indigauge_session_failed)

	indigauge.start("YOUR_PUBLIC_KEY", "My Game", "1.0.0")

func _on_indigauge_session_started(_session_token: String) -> void:
	print("Indigauge session started")

func _on_indigauge_session_failed(_code: int, message: String) -> void:
	push_warning("Indigauge session failed: " + message)

#Autoload setup

Register res://addons/indigauge/client.gd as an autoload named Indigauge. Then start it from your main scene or boot script:

func _ready() -> void:
	Indigauge.start("YOUR_PUBLIC_KEY", "My Game", "1.0.0")

#Inspector setup

For a no-code startup path:

1. Select the IndigaugeClient node.
2. Set public_key, game_name, and game_version.
3. Leave mode as AUTO.
4. Enable auto_start_session.

The addon resolves empty game_name and game_version values from the Godot project settings when possible.

#Runtime modes

AUTO is the recommended default. It uses DEV mode in the Godot editor and debug exports, and LIVE mode in release exports.

To force live telemetry while running from the editor:

indigauge.mode = IndigaugeTypes.Mode.LIVE
indigauge.start("YOUR_PUBLIC_KEY", "My Game", "1.0.0")

#Send events

Events are queued after a session starts and flushed automatically. In DEV mode, event batches are printed locally instead of being sent to the API.

indigauge.ig_info("game.start")
indigauge.ig_info("player.jump", {"height": 2.4})
indigauge.ig_warn("network.retry", {"attempt": 2})
indigauge.ig_error("save.failed", {"reason": "disk_full"})

Event names must follow the same format as the Rust SDK:

• Use exactly one dot: namespace.event.
• Use only ASCII letters on both sides of the dot.
• Do not use numbers, underscores, spaces, or multiple dots.
• Put dynamic values in metadata, not the event name.

Good event names:

game.start
player.jump
level.clear
ui.open

Invalid event names:

game_start
level.3.clear
ui.button.click
store.purchase1

See the Event Naming guide for more detail.

#Track session metadata

Session metadata describes the whole play session. Use it for state that you want to inspect alongside sessions and events, such as level, difficulty, region, build channel, character class, matchmaking mode, or experiment assignment.

indigauge.set_session_metadata({
	"difficulty": "hard",
	"region": "eu",
})

indigauge.set_session_metadata_value("character", "ranger")
indigauge.update_session_metadata({"level": 3, "matchmaking": "ranked"})
indigauge.remove_session_metadata_value("region")

When a session is active, metadata changes are sent with the next flush or as soon as the client can send them. In DEV mode, the update is logged locally.

#Collect player feedback

The addon includes a feedback panel. By default, players can press F2 to toggle it.

indigauge.show_feedback_panel()
indigauge.toggle_feedback_panel()

You can also open it from your own UI:

func _on_feedback_button_pressed() -> void:
	indigauge.ig_info("ui.open", {"screen": "feedback"})
	indigauge.show_feedback_panel()

The panel supports categories, optional question/context text, message validation, Escape-to-close behavior, and optional screenshot upload.

To submit feedback directly:

indigauge.submit_feedback("The jump timing feels inconsistent.", "bugs")
indigauge.submit_feedback(
	"Please add more controller settings.",
	"controls",
	"What would make controls better?",
	true
)

The fourth argument controls whether the addon captures and uploads a screenshot.

Accepted feedback categories are:

bugs, general, ui, performance, gameplay, controls, audio, balance,
graphics, visual, art, other

Unknown or empty categories are sent as other.

#Configuration reference

Set these exported properties before calling start(...), or configure them in the Inspector.

After setup(...) or start(...), advanced batching settings are available on client.config:

Example:

indigauge.setup("YOUR_PUBLIC_KEY", "My Game", "1.0.0")
indigauge.config.batch_size = 32
indigauge.config.flush_interval_sec = 5.0
indigauge.start_session()

#API reference

#Startup

indigauge.start(public_key, game_name, game_version, api_base = "")
indigauge.setup(public_key, game_name, game_version, api_base = "", start_now = false)
indigauge.start_session()

Use start(...) for normal integrations. Use setup(...); start_session() when you need to adjust client.config before the first session request.

#Events

indigauge.ig_trace(event_type, metadata = {})
indigauge.ig_debug(event_type, metadata = {})
indigauge.ig_info(event_type, metadata = {})
indigauge.ig_warn(event_type, metadata = {})
indigauge.ig_error(event_type, metadata = {})

#Session metadata

indigauge.set_session_metadata(metadata)
indigauge.update_session_metadata(metadata)
indigauge.set_session_metadata_value(key, value)
indigauge.remove_session_metadata_value(key)
indigauge.get_session_metadata()
indigauge.flush_session_metadata()

#Feedback

indigauge.show_feedback_panel(parent = null)
indigauge.hide_feedback_panel()
indigauge.toggle_feedback_panel(parent = null)
indigauge.submit_feedback(message, category, question = "", include_screenshot = false)

#Signals

#Example project

The repository includes an importable Godot project at godot-addon/example/. It demonstrates a small Breakout-style game with gameplay events, session metadata, and feedback.

1. Open Godot.
2. Choose Import.
3. Select godot-addon/example/project.godot.
4. Run the project.
5. Play with A/D, Left/Right, Space, or the mouse.
6. Press F2 or click Feedback to test the feedback panel.

The example uses Mode.AUTO, so it runs as a local DEV session from the editor. Replace YOUR_PUBLIC_KEY before creating a release export.

#Production checklist

• Set a real public_key.
• Use a stable game_name.
• Set game_version from your release or build pipeline.
• Leave mode as AUTO unless you need to force a specific mode.
• Verify release exports include the files under addons/indigauge/.
• Listen to session_failed and log the returned message during QA.
• Test the feedback panel with your production input map and UI layer stack.
• Avoid putting personally identifiable information in event metadata.

#Troubleshooting

#No data appears in Indigauge

• Confirm the build is running in LIVE mode. AUTO is local DEV mode in the editor and debug exports.
• Confirm public_key is set before start(...).
• Connect to session_failed and inspect the returned message.

#Events are not sent

• Events are queued only after a session has started.
• Event names must use the strict namespace.event format.
• Event names can only contain letters and one dot.
• In DEV mode, events are logged locally instead of sent to the API.

#F2 does not open the feedback panel

• Confirm feedback_hotkey_enabled is true.
• Confirm another script is not consuming F2 first.
• Call indigauge.show_feedback_panel() directly to verify the panel loads.

#The feedback panel appears behind other UI

• Increase feedback_canvas_layer.
• Or pass your own parent to show_feedback_panel(parent).