Native in-game notifications

CMAPI 1.0.0 exposes Planet Crafter's own HUD notification systems through a small, Unity-free mod API. CMAPI does not draw a competing overlay or imitate the game's interface.

Built-in behavior

Successful give_item grants show the native inventory information card with the item's game icon, localized name, inventory marker, and amount. Successful give_money/give_tokens grants show Planet Crafter's normal Terra Token gain popup.

Use this command to verify the HUD path without changing the world:

notify CMAPI notifications are working

Automatic grant notices can be disabled without disabling the commands or the public notification service:

{
  "ShowGameplayNotifications": false
}

Mod API

Every mod receives IModHelper.Notifications:

helper.Notifications.Show("Air filter maintenance complete.");
helper.Notifications.ShowItemAdded("Iron", 3);
helper.Notifications.ShowTerraTokensAdded(250);

Show uses Planet Crafter's native tutorial/information card. ShowItemAdded resolves an exact stable item ID and uses the game's item icon and localized display name. ShowTerraTokensAdded uses the game's larger Terra Token popup.

Notifications may be queued from any thread. CMAPI delivers them from the game thread when the required HUD manager exists. The queue:

• holds at most 50 entries globally;
• delivers at most five entries per frame;
• expires an entry after 20 seconds if no compatible HUD becomes available;
• discards notifications owned by a mod whose startup fails;
• isolates and logs a display failure without affecting the game or later notifications.

Messages accept 1–300 characters. General/item notification durations accept 1–15 seconds. Item and token amounts accept 1–1,000,000 for display purposes.

Mutation API integration

IItemManager.AddToLocalBackpackAsync and ITerraTokenManager.AddAsync automatically queue the matching native notification after a successful host-authorized mutation. A mod should not call ShowItemAdded or ShowTerraTokensAdded again for the same mutation unless it deliberately wants a second message.

Notifications are local presentation. They do not send chat, messages, or popups to another multiplayer client. A future remote-notification API should only be added with explicit network permission and rate limiting.