[Lib] TutorialTips

Overview

Small helper for tutorial tips that display only once per profile. Originally by Lemonymous. Extended here with optional custom rootId via init so shared libs like WeaponPreview can own a tip namespace across mods.

Note: Each mod using this library must each have their unique instance of it (or call init with a dedicated root id).

Any issues or concerns? Join the Redacted Rice Discord and @Das Keifer

API

• tutorialTips
  • init
  • add
  • trigger
  • reset
  • resetAll
  • getCachedProfileData

 

tutorialTips

A library providing functions to add and trigger tutorial tips. Tips can be triggered only once per profile, unless reset by reset or resetAll.

Tips are stored under modcontent.lua -> tutorialTips[rootId].

PascalCase aliases are also available: Init, Add, Trigger, Reset, ResetAll.

 

init

Argument name	Type	Description
customRootId	string	(optional) Namespace for tip storage/ids. Defaults to the current mod's id

Sets the root id used for Global_Texts keys and profile storage, then refreshes the profile cache. Call this when a shared lib needs its own tip namespace instead of the loading mod's id.

Returns self for chaining.

Example:

local tutorialTips = require(self.scriptPath .. "libs/tutorialTips")
tutorialTips:init("weaponPreview")

 

add

Argument name	Type	Description
tip	table	A table describing the tutorial tip

The tip object, passed as first argument, can have the following fields:

Field	Type	Description
id	string	Id of tutorial tip. Unique within the root namespace
title	string	Description title of tutorial tip
text	string	Description text of tutorial tip

Adds a tutorial tip that can be triggered exactly once with trigger. Registers Global_Texts entries as rootId .. id .. "_Title" / "_Text".

Example:

tutorialTips:add({
    id = "MultiIconNotification",
    title = "Grouped Icons",
    text = "Multiple effects on one tile are shown as a multi-icon. Hold H for details.",
})

 

trigger

Argument name	Type	Description
id	string	Id of tutorial tip you want to trigger
loc	Point	The tile you want the tutorial tip to point at

Triggers tutorial tip with the specified id at the specified location. Displaying the tip's title and text until the player dismisses the tip.

Additional calls to trigger will no longer do anything on the current profile unless reset or resetAll is used to reset this tutorial tip. No ops in the map editor.

Example:

tutorialTips:trigger("MultiIconNotification", loc)

 

reset

Argument name	Type	Description
id	string	Id of tutorial tip you want to reset

Resets the tutorial tip, so it can be triggered again.

Example:

tutorialTips:reset("MultiIconNotification")

 

resetAll

Resets every tutorial tip added under the current rootId, so you can trigger them again. Typical hook for a mod option.

Example:

tutorialTips:resetAll()

 

getCachedProfileData

Returns the cached tutorialTips[rootId] table for the current profile, or nil before cache.

Example:

local data = tutorialTips:getCachedProfileData()