# Unlockable Items

The unlockables feature allows to manage items, which have a persistent state of being either locked or unlocked. You can use it in a variety of ways, for example to represent slots in a CG or movie gallery, achievements, tips and other systems where some entity should be able to become unlocked or activated when player satisfies a condition.

Each unlockable item is represented by a string identifier and boolean value, indicating whether the item is unlocked. In naninovel scripts, use @unlock and @lock commands to respectively unlock and lock an item with a specific ID, eg:

@unlock SecretAchievement

— will unlock item SecretAchievement and

@lock SecretAchievement

— will lock it back.

The unlockable state of the items is stored under global scope and doesn't depend on local game sessions; eg, if you unlock some item, it won't become locked again when player starts a new game or loads another saved game.

To bind an actual GameObject with the unlockable item, use UnlockableTrigger component:

Set the item's ID to the Unlockable Item Id field and bind an command that should be performed when the items is unlocked. The illustration above, for example, makes the GameObject active when SecretAchievement is unlocked and vice versa.

In C# you can access the unlockable items using UnlockableManager engine service.

# Unlockable Resources

Under the unlockables configuration menu (Naninovel -> Configuration -> Unlockables), you can find resources manager, that allows to store arbitrary assets to be used with the unlockables feature.

The unlockable resources are used by the built-in unlockable systems, such as CG Gallery. You can also utilize the manager for you own custom systems.

Using the CG gallery feature, you can specify texture resources (images), that can be unlocked throughout the game and then browsed via the ICGGalleryUI UI accessible from the title menu.

By default, all the unlockable texture resources with CG prefix added via unlockable resources manager and background sprite resources of the MainBackground actor with the same prefix will be considered unlockable CG items.

To add an unlockable CG item to the gallery, you can either use one of the existing main background resources, by prepending CG to its path:

— or add a "standalone" texture using the unlockable resources manager, accessible with Naninovel -> Resources -> Unlockables:

No matter which way you'll choose, you can then unlock and lock the items using @unlock and @lock commands respectively.

For example, to unlock the CG/Map item added in the illustrations above, use the following script command:

@unlock CG/Map

In case you'll use both unlockable and background resources to add the CG items, the resources specified in the unlockables manager will be displayed in the CG gallery first. You can change this behavior as well as the actual sources from where the available CG resources are retrieved using Cg Sources property of CG Gallery Panel script, attached to the root of UI prefab representing the CG Gallery (built-in implementation stored at Naninovel/Prefabs/DefaultUI/ICGGalleryUI.CGGalleryPanel).

When there is at least one CG item added to any of the sources (no matter the unlocked state), CG GALLERY button will appear in the title menu allowing to access the CG Gallery browser.

You can modify or completely replace the built-in ICGGalleryUI implementation using the UI customization feature.

# Tips

Unlockable tips system allows to specify a set of text records using localizable managed text documents; the records can then be unlocked throughout the game and be browsed via the ITipsUI UI accessible from the title menu and text printer control panels.

The system can be used to build an in-game vocabulary/encyclopedia or achievements tracker.

To define the available tips, create a Tips.txt text document inside the managed text resources directory (Resources/Naninovel/Text by default). Each line identifies a single tip record. The line should begin with tip ID followed by colon; then the tip's title, category (optional) and description should be specified, all separated by vertical lines (|), eg:

Tip1ID: Tip 1 Title | Tip 1 Category | Tip 1 Description
Tip2ID: Tip 2 Title || Tip 2 Description
Tip3ID: Tip 3 Title 
Tip4ID: Tip 4 Title | Tip 4 Category |

You can use rich text tags and insert line breaks (\n) inside the description section of the tip records.

When there is at least one tip record in the Tips.txt managed text document, "TIPS" button will appear in the main menu and control panels, leading to the tips browser.

To unlock a tip record, use @unlock and @lock to lock the record back followed by the tip ID (should always be preceded by Tips/ prefix) in the naninovel scripts. Eg, to unlock a Tip1ID tip record use:

@unlock Tips/Tip1ID
Обновлено: June 29, 2020