From ecaae697a8bffc50a5a9ff033bbb7827be826e5e Mon Sep 17 00:00:00 2001
From: Kelly Rauchenberger <fefferburbia@gmail.com>
Date: Thu, 18 Feb 2021 18:57:37 -0500
Subject: Added documentation to the message-related script functions

---
 res/scripts/common.lua | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

(limited to 'res/scripts/common.lua')

diff --git a/res/scripts/common.lua b/res/scripts/common.lua
index 2e6a7e2..4dfa1a2 100644
--- a/res/scripts/common.lua
+++ b/res/scripts/common.lua
@@ -32,12 +32,17 @@ SpriteLayer = {
 
 gamestate = {}
 
+--- Yields until the specified amount of time has passed.
+-- @param time in milliseconds
 function Delay(time)
   while time > 0 do
     time = time - coroutine.yield()
   end
 end
 
+--- Starts a cutscene.
+-- This takes care of showing the cutscene bars, as well as halting character
+-- movement. It does not block.
 function StartCutscene()
   local playerId = getPlayerSprite()
   local playerSprite = getSprite(playerId)
@@ -46,24 +51,42 @@ function StartCutscene()
   message():displayCutsceneBars()
 end
 
+--- Queues a message for display.
+-- Non-blocking! If you want to block until the message has been fully
+-- revealed, use WaitForEndOfMessage().
+-- @param msg the text of the message
+-- @param name the name of the character speaking (leave blank to not show a character name)
+-- @param type the SpeakerType for the character, which determines which beep sound is played, if any
 function DisplayMessage(msg, name, type)
   message():displayMessage(msg, name, type)
 end
 
+--- Queues a choice prompt for the player.
+-- This should be called after DisplayMessage(), as it is not valid for a choice
+-- prompt to be the first line of the text box. This also does not block. You
+-- should use WaitForEndOfMessage() after this.
+-- @param one the text of the first option
+-- @param two the text of the second option
 function ShowChoice(one, two)
   message():showChoice(one, two)
 end
 
+--- Gets the result of the last choice prompt.
+-- @return 0 for the left choice, 1 for the right choice
 function GetChoiceSelection()
   return message():getChoiceSelection()
 end
 
+--- Yields until all queued messages / choice prompts have been dismissed.
+-- This does not hide the cutscene bars, nor does it wait for them to hide.
 function WaitForEndOfMessage()
   while (message().isMessageActive) do
     coroutine.yield()
   end
 end
 
+--- Hides the cutscene bars.
+-- This also re-enables player movement.
 function HideCutsceneBars()
   WaitForEndOfMessage()
   message():hideCutsceneBars()
-- 
cgit 1.4.1