Custom Events
Track specific game actions with hierarchical event keys.
Custom events let developers track specific in-game actions. Event keys should follow a structured, hierarchical format to keep analytics tracking consistent.
Hammer.Instance.ANALYTICS_CustomEvent(KEY_STRING, VALUE_FLOAT);Usage example
Hammer.Instance.ANALYTICS_CustomEvent($"InGame:Concepts:TaskCompletedWithItems:{conceptId.ToString()}:{taskId.ToString()}",
LevelManager.Instance.GetLevel());Event key structure
Event keys are colon-separated strings defining a hierarchy — e.g. UI:Button:Shop:Clicked. Keys can have up to 5 levels, structured as Category:Subcategory:Subcategory:.... Keep the number of unique keys reasonable.
| Example key | Description |
|---|---|
UI:Button:Shop:Clicked | Tracks when the shop button is clicked. |
Player:Skill:Fireball:Used | Tracks when a player uses a skill. |
SpecialEvent:SpringFestival:2025 | Tracks participation in a seasonal event. |
Player:Item:Purchased:Sword_123 | Tracks an item purchase (with a unique identifier). |
GameMode:Ranked:MatchStarted | Tracks when a ranked match begins. |
Quest:MainStory:Act2:Completed | Tracks when a player completes Act 2 of the story. |
Inefficient event key example
When event keys contain too many parameter combinations, you end up with an overwhelming number of possible event keys — hurting performance and making analysis difficult. Example:
zone:[playerAction]:[scoreAchieved]Assumptions:
zonecontains 50 different levels or areas.playerActioncontains 200 different action types.scoreAchievedranges from 0 to 1000.
This results in 50 × 200 × 1000 = 10,000,000 possible event combinations — too many to analyze meaningfully.
Instead, simplify by sending scoreAchieved as the floating-point value:
Hammer.Instance.ANALYTICS_CustomEvent("Game:ActionCompleted:Zone" + zone + ":Action" + playerAction,
scoreAchieved);This keeps the event key simple and avoids excessive combinations.
Parameter usage
Warning: This overload is not fully supported across all analytics SDKs yet. Do not use this overload unless you need detailed data that can't be sent through subcategories.
To avoid overly complex event keys, attach additional metadata via a dictionary parameter:
Hammer.Instance.ANALYTICS_CustomEvent(KEY_STRING, new Dictionary<string, object>() {
{ "KillCount", killCount },
{ "MissionId", id },
{ "Duration", duration }
});