Lua utility module Diary
+Diaries: + The module provides functions to create and manage Diaries.
++
It maintains diary definitions and entries through all levels and hubs. + Each diary is accessed by the object that was used to create it.
+ +Example usage:
+ + ++local CustomDiary = require("Engine.CustomDiary") + +--This function creates a diary from the DiarySetup.lua template file in script folder +CustomDiary.ImportDiary("DiarySetup") + +--This method gets the diary that was created with the DIARY_ITEM object and stores it in variable diary. +local diary = CustomDiary.Get(TEN.Objects.ObjID.DIARY_ITEM) +--This method opens the diary on the 3rd page +diary:showDiary(3) ++ + + + +
Functions
+| CustomDiary.ImportDiary(fileName) | +Imports diary from an external file. | +
| CustomDiary.Create(object, objectIdBg, spriteIdBg, colorBg, pos, rot, scale, alignMode, scaleMode, blendMode, alpha, pageSound, exitSound) | +Creates a diary with extensive configuration options. | +
| CustomDiary.Get(object) | +The function retrieves a diary by its unique object. | +
| CustomDiary.Delete(object) | +The function removes a custom diary and its associated data from the system. | +
| CustomDiary.Status(value) | +The function adds the callback to enable diaries in levels. | +
| CustomDiary:IsVisible() | +The function checks whether the specified diary is currently visible. | +
| CustomDiary:ShowDiary(pageIndex) | +The function displays the specified diary. | +
| CustomDiary:GetUnlockedPageCount() | +The function returns the number of unlocked pages in the diary. | +
| CustomDiary:UnlockPages(pageIndex, notification) | +The function unlocks the specified diary up to the given page number. | +
| CustomDiary:ClearPage(pageIndex) | +The function clears the page for the diary. | +
| CustomDiary:AddTextEntry(pageIndex, text, textPos, textOptions, textScale, textColor) | +Adds a text entry to the specified page for the diary. | +
| CustomDiary:AddImageEntry(pageIndex, objectId, spriteId, color, pos, rot, scale, alignMode, scaleMode, blendMode) | +Adds an image entry to the specified page for the diary. | +
| CustomDiary:AddNarration(pageIndex, trackName) | +Add a narration track in the voice channel to the page. | +
| CustomDiary:RemoveNarration(pageIndex) | +Remove the narration track from the page of the specified diary. | +
| CustomDiary:AddBackground(objectId, spriteId, color, pos, rot, scale, alignMode, scaleMode, blendMode, alpha) | +Add a background image for the diary. | +
| CustomDiary:ClearBackground() | +Clears settings for the background for the specified diary. | +
| CustomDiary:CustomizeNotification(notificationTime, objectId, spriteId, color, pos, rot, scale, alignMode, scaleMode, blendMode, notificationSound) | +Customizes the notification icon and sound for the diary. | +
| CustomDiary:ClearNotification() | +Clears settings for the notification system for the specified diary. | +
| CustomDiary:CustomizePageNumbers(pageNoType, prefix, separator, textPos, textOptions, textScale, textColor) | +Customizes the page numbers for the diary. | +
| CustomDiary:ClearPageNumbers() | +Clears settings for the page numbers for the specified diary. | +
| CustomDiary:CustomizeControls(textPos, textOptions, textScale, textColor) | +Customizes the controls text for the diary. | +
| CustomDiary:CustomizeControlsText(string1, string2, string3, string4, separator) | +Customizes the display text for controls for specified diary. | +
| CustomDiary:ClearControls() | +Clears settings for the specified diary's controls text. | +
+
+ + +
Functions
+ +-
+
- + + CustomDiary.ImportDiary(fileName) + +
-
+ Imports diary from an external file. There are different types that must be defined. (diary, background, controls, pageNumbers, notification, image, text, narration). Each of the section's arguements are the same as the functions described in this documentation.
+ Refer to DiarySetup.lua file for a sample script.
+
+
+
+
Parameters:
+-
+
- fileName + string + Name of file in the script folder without extension to import the diary from. + +
+ - + + CustomDiary.Create(object, objectIdBg, spriteIdBg, colorBg, pos, rot, scale, alignMode, scaleMode, blendMode, alpha, pageSound, exitSound) + +
-
+ Creates a diary with extensive configuration options.
+ Parameters:
+
+
+
+
Parameters:
+-
+
- object + ObjID + The pickup object that will be used to create the diary. The diary can be created using PICKUPITEMX (596-611) or DIARYITEM (986). Access the diary by selecting the item in the inventory. + +
- objectIdBg + ObjID + Object ID for the diary's sprite. + +
- spriteIdBg + int + SpriteID from the specified object for the diary's sprite. + +
- colorBg + Color + Color of diary's sprite. + +
- pos + Vec2 + X,Y position of the bar's background in screen percent (0-100). + +
- rot + float + rotation of the diary's sprite (0-360). + +
- scale + Vec2 + X,Y Scaling factor for the bar's background sprite. + +
- alignMode + AlignMode + Alignment for the diary's sprite. + +
- scaleMode + ScaleMode + Scaling for the diary's sprite. + +
- blendMode + BlendID + Blending modes for the diary's sprite. + +
- alpha + number + alpha value for the diary's sprite (0-255). + +
- pageSound + Sound + Sound to play with page turn. + +
- exitSound + Sound + Sound to play when existing the diary. + +
Returns:
+-
+
+ CustomDiary
+
+
+
+
+ - + + CustomDiary.Get(object) + +
-
+ The function retrieves a diary by its unique object. This function is useful when you need to access or manipulate a diary that has already been created .
+
+
+
+
Parameters:
+-
+
- object + ObjID + The pickup object that was used to create the diary (596-611,986). + +
Returns:
+-
+
+ CustomDiary
+ The diary created using the object.
+
+ - + + CustomDiary.Delete(object) + +
-
+ The function removes a custom diary and its associated data from the system. It ensures that the diary is no longer tracked or accessible in the LevelVars.Engine.Diaries.
+ Please call this once a diary has served its purpose. It helps reduce the savegame size.
+
+
+
+
Parameters:
+-
+
- object + ObjID + The pickup object that was used to create the diary (596-611,986). + +
+ - + + CustomDiary.Status(value) + +
-
+ The function adds the callback to enable diaries in levels. This needs to be added to every level preferably in the LevelFuncs.OnStart.
+
+
+
+
Parameters:
+-
+
- value + bool + True enables the diaries to be activated. False would disable the diaries. + +
+ - + + CustomDiary:IsVisible() + +
-
+ The function checks whether the specified diary is currently visible.
+
+
+
+
+
Returns:
+-
+
+ bool
+ true if the diary is visible and false if it is not.
+
+ - + + CustomDiary:ShowDiary(pageIndex) + +
-
+ The function displays the specified diary. Can be used to call the diary directly using volume or classic triggers.
+
+
+
+
Parameters:
+-
+
- pageIndex + int + The page number at which diary should be opened. + +
+ - + + CustomDiary:GetUnlockedPageCount() + +
-
+ The function returns the number of unlocked pages in the diary.
+
+
+
+
+
Returns:
+-
+
+ int
+ total number of unlocked pages in the diary.
+
+ - + + CustomDiary:UnlockPages(pageIndex, notification) + +
-
+ The function unlocks the specified diary up to the given page number.
+ This value can be overridden to lock or unlock pages as needed. + A lower number can be set to restrict access to previously unlocked pages. + + + +Parameters:
+-
+
- pageIndex + int + The page number up to which the diary should be unlocked. + +
- notification + bool + If true, and notification has been defined, a notification icon and sound will be played. + +
+ - + + CustomDiary:ClearPage(pageIndex) + +
-
+ The function clears the page for the diary.
+
+
+
+
Parameters:
+-
+
- pageIndex + int + The page number to be cleared. + +
+ - + + CustomDiary:AddTextEntry(pageIndex, text, textPos, textOptions, textScale, textColor) + +
-
+ Adds a text entry to the specified page for the diary.
+
+
+
+
Parameters:
+-
+
- pageIndex + int + page number to add the text entry to. + +
- text + string + Text entry to be added to the page. + +
- textPos + Vec2 + X,Y position of the text. + +
- textOptions + DisplayStringOption + alignment and effects for the text. Default: None. Please note text is automatically aligned to the LEFT + +
- textScale + number + Scale factor for the text. + +
- textColor + Color + Color of the text. + +
+ - + + CustomDiary:AddImageEntry(pageIndex, objectId, spriteId, color, pos, rot, scale, alignMode, scaleMode, blendMode) + +
-
+ Adds an image entry to the specified page for the diary.
+
+
+
+
Parameters:
+-
+
- pageIndex + int + page number to add the image entry to. + +
- objectId + ObjID + Object ID for the image entry sprite. + +
- spriteId + number + SpriteID from the specified object for the image entry. + +
- color + Color + Color of image entry. + +
- pos + Vec2 + X,Y position of the image entry in screen percent (0-100). + +
- rot + number + rotation of the image entry (0-360). + +
- scale + Vec2 + X,Y Scaling factor for the image entry. + +
- alignMode + AlignMode + Alignment for the image entry. + +
- scaleMode + ScaleMode + Scaling for the image entry. + +
- blendMode + BlendID + Blending modes for the image entry. + +
+ - + + CustomDiary:AddNarration(pageIndex, trackName) + +
-
+ Add a narration track in the voice channel to the page. Track is played with the draw button.
+
+
+
+
Parameters:
+-
+
- pageIndex + int + page number to add the narration track to. + +
- trackName + string + of track (without file extension) to play. + +
+ - + + CustomDiary:RemoveNarration(pageIndex) + +
-
+ Remove the narration track from the page of the specified diary.
+
+
+
+
Parameters:
+-
+
- pageIndex + int + page number to remove the narration track from. + +
+ - + + CustomDiary:AddBackground(objectId, spriteId, color, pos, rot, scale, alignMode, scaleMode, blendMode, alpha) + +
-
+ Add a background image for the diary.
+
+
+
+
Parameters:
+-
+
- objectId + ObjID + Object ID for the diary's background. + +
- spriteId + number + SpriteID from the specified object for the diary's background. + +
- color + Color + Color of diary's background. + +
- pos + Vec2 + X,Y position of the diary's background in screen percent (0-100). + +
- rot + float + rotation of the diary's background sprite (0-360). + +
- scale + Vec2 + X,Y Scaling factor for the diary's background. + +
- alignMode + AlignMode + Alignment for the diary's background. + +
- scaleMode + ScaleMode + Scaling for the diary's background. + +
- blendMode + BlendID + Blending modes for the diary's background. + +
- alpha + number + alpha value for the diary's background (0-255). + +
+ - + + CustomDiary:ClearBackground() + +
- + Clears settings for the background for the specified diary. + + + + + + + + + +
- + + CustomDiary:CustomizeNotification(notificationTime, objectId, spriteId, color, pos, rot, scale, alignMode, scaleMode, blendMode, notificationSound) + +
-
+ Customizes the notification icon and sound for the diary.
+
+
+
+
Parameters:
+-
+
- notificationTime + number + Time in seconds the notification icon will show on screen. + +
- objectId + ObjID + Object ID for the notification icon. + +
- spriteId + number + SpriteID from the specified object for the notification icon. + +
- color + Color + Color of notification icon. + +
- pos + Vec2 + X,Y position of the notification icon in screen percent (0-100). + +
- rot + number + rotation of the notification icon (0-360). + +
- scale + Vec2 + X,Y Scaling factor for the notification icon. + +
- alignMode + AlignMode + Alignment for the notification icon. + +
- scaleMode + ScaleMode + Scaling for the notification icon. + +
- blendMode + BlendID + Blending modes for the notification icon. + +
- notificationSound + Sound + Sound to play with notification icon. + +
+ - + + CustomDiary:ClearNotification() + +
- + Clears settings for the notification system for the specified diary. + + + + + + + + + +
- + + CustomDiary:CustomizePageNumbers(pageNoType, prefix, separator, textPos, textOptions, textScale, textColor) + +
-
+ Customizes the page numbers for the diary.
+
+
+
+
Parameters:
+-
+
- pageNoType + int + Specifies the format for page numbers (1 or 2). 1: Displays only the current page number. 2: Formats the page number as: [Prefix][CurrentPage][Separator][UnlockedPages]. + +
- prefix + string + Prefix to be added for type 2 of page numbers. + +
- separator + string + Separator to be added for type 2 of page numbers. + +
- textPos + Vec2 + X,Y position of the page numbers. + +
- textOptions + DisplayStringOption + alignment and effects for the text. Default: None. Please note text is automatically aligned to the LEFT + +
- textScale + number + Scale factor for the page numbers. + +
- textColor + Color + Color of the page numbers. + +
+ - + + CustomDiary:ClearPageNumbers() + +
- + Clears settings for the page numbers for the specified diary. + + + + + + + + + +
- + + CustomDiary:CustomizeControls(textPos, textOptions, textScale, textColor) + +
-
+ Customizes the controls text for the diary.
+
+
+
+
Parameters:
+-
+
- textPos + Vec2 + X,Y position of the controls text. + +
- textOptions + DisplayStringOption + alignment and effects for the text. Default: None. Please note text is automatically aligned to the LEFT. + +
- textScale + number + Scale factor for the controls. + +
- textColor + Color + Color of the page controls. + +
+ - + + CustomDiary:CustomizeControlsText(string1, string2, string3, string4, separator) + +
-
+ Customizes the display text for controls for specified diary.
+
+
+
+
Parameters:
+ + + + + + +
+ - + + CustomDiary:ClearControls() + +
- + Clears settings for the specified diary's controls text. + + + + + + + + + +