腳本標籤(label)和主控流程

label語句

label語句允許使用自訂的標籤名聲明一個程序點位。這些標籤僅僅用來被調用或者跳轉，可以使用在Ren’Py腳本、python函數及各類界面中。

label sample1:
    "這是一個'sample1'腳本標籤。"

label sample2(a="default"):
    "這是一個'sample2'腳本標籤。"
    "a = [a]"

一個label語句可能只跟某一個語句塊(block)關聯。在那種情況下，主控流程遇到label語句就會進入關聯語句塊(block)，並順序執行之後的語句。

總共有兩種腳本標籤(label)：global 和 local 。global標籤在所有項目文件中都生效，所以每個遊戲中都不能重複定義。 local標籤可以同名，但需要與不同的global標籤做關聯。 需要聲明一個local標籤的話，在標籤名前綴一個英文句號“.”即可。例如：

label global_label:
    "這在一個global腳本標籤裡。"
label .local_label:
    ".這裡屬於local腳本標籤。"
    jump .another_local
label .another_local:
    "另一個local腳本標籤"
    jump .local_label

local腳本標籤在關聯的global標籤內部可以直接引用。其他地方則需要使用標籤全名，由關聯的globle標籤和local標籤組成。 一個關於global標籤和local標籤的例子如下：

label another_global:
    "現在讓我們跳轉進入其他地方的local腳本標籤。"
    jump global_label.local_name

lable語句可以帶一些可選參數。這些參數的處理在 PEP 3102 中有詳細說明，這裡僅說兩種例外:

• 語句被調用時，才計算默認參數的值。

• 變數具有動態生命週期。

如果某個變數具有動態生命週期，它的值會持續到其所屬的label標籤中出現一個return語句為止。 嘗試使用jump或previous語句傳遞該變數的值都是不明智的。 帶有參數的label樣例，詳見 call語句 。

jump語句

jump語句用於將主控流程轉入指定的腳本標籤(label)處。

若出現了 expression (表達式)關鍵字，關鍵字後面的表達式將被賦值，而被計算後的對應字串則會被用作跳轉目標的標籤語句。若未出現 expression (表達式)關鍵字，跳轉目標的標籤名字就必須精確指定。

與call語句不同，jump語句不會將下一個語句放入棧(stack)中。因此，執行完跳轉標籤對應的語句塊之後，主控流程不會回到跳轉前的腳本位置。

label loop_start:

    e "哦，不！看起來我們陷入了一個無限循環之中。"

    jump loop_start

call語句

call語句用於將主控流程轉入給定的腳本標籤(label)處。call語句會將下一條語句壓入到調用棧(stack)中，並允許主控流程在執行完這次調用後，回到調用發生的腳本位置。

若出現了 expression (表達式)關鍵字，關鍵字後面的表達式將被賦值，而被計算後的對應字串則會被用作跳轉目標的標籤語句。若未出現 expression (表達式)關鍵字，跳轉目標的標籤名字就必須精確指定。

from 分句是可選的，在label語句後面直接添加入參名和值，並直接在該label下直接使用。一個命名直接的標籤(lable)有助於我們能利用棧(stack)回到腳本裡合適的地方，就算載入的是修改過的腳本。

call語句可以使用參數，詳見 PEP 448。

當我們使用一個帶入參列表的調用表達式時，必須在表達式和入參列表之間插入關鍵字 pass 。 否則，入參列表會被當作表達式的一部分，而不是call語句的一部分。

label start:

    e "首先，我們調用一個支線。"

    call subroutine

    call subroutine(2)

    call expression "sub" + "routine" pass (count=3)

    return

label subroutine(count=1):

    e "我來過這裡 [count] 次了。"
    e "接著，我們會從支線返回。"

    return

Warning

每條 call 語句後面都不加上 from 從句就發布遊戲是危險的。當然也可以通過發布更新補丁解決。 在沒有 from 從句的情況下，編輯 call 相關的腳本，可能會有存檔損壞的風險。

構建發行版時，將選項“向call語句添加from從句”勾選上就能解決以上問題。

return語句

return語句會在調用棧中彈出最頂層的那條語句，並將主控流程轉到那條語句。若調用棧為空，返回語句將重啟Ren’Py，將主控流程切換至主選單。

若返回語句帶有可選項表達式，表達式會被計算求值，並且結果會被儲存在_return變數中。_return變數依賴於各種場景動態變化。

特殊腳本標籤(label)

以下腳本標籤(label)會在Ren’Py中使用：

start

默認情況下，Ren’Py在遊戲啟動後會跳轉至這個標籤。

quit

若該標籤存在，當用戶退出遊戲時該標籤內容會被調用。

after_load

若該標籤存在，當遊戲讀檔後會調用這個標籤內容。其可能被用於遊戲內容更新後的數據修復。 如果數據從此標籤後發生變化，應該調用 renpy.block_rollback() 函數防止用戶從該存檔點回滾。

splashscreen

若該標籤存在，遊戲首次運行時，在主選單出現前，該標籤內容會被調用。 詳見 添加啟動畫面 。

before_main_menu

若該標籤存在，在主選單出現前，該標籤內容會被調用。在少數情況下，其用來設置主選單，例如背景播放一段影片。

main_menu

若該標籤存在，標籤內容會被調用，用來替代預設的主選單。若其內容中包含return語句，Ren’Py將從start標籤處開始遊戲。例如，下面這段腳本在不顯示主選單的情況下開始遊戲。

label main_menu:
    return

after_warp

若該標籤存在，則調用warp語句時，此標籤至傳送(warp)點前的語句都將被執行。詳見 傳送至某行

hide_windows

若該標籤存在，當玩家使用滑鼠右鍵或鍵盤H鍵隱藏對話窗口時，將調用此標籤。 若標籤返回值為True，隱藏對話窗口行為將取消(依然當作隱藏已經發生)。否則，繼續隱藏對話窗口。

腳本標籤(label)和主控流程函數

renpy.call_in_new_context(label, *args, **kwargs)

該函數創建一個新的上下文(context)，並從這個上下文(context)中給定的腳本標籤(label)處開始執行Ren’Py腳本。新的上下文(context)中禁用了回滾功能，並且存檔/讀檔會發生在頂層的上下文(context)中。

使用該函數可以在原有交互中啟動第二層交互。

renpy.get_all_labels()

返回程序中定義所有標籤(lable)的集合，包括在庫(library)中定義為僅限內部引用的標籤。

renpy.get_return_stack()

返回一個當前返回(return)棧(stack)的列表。返回棧是一個語句名組成的列表。

該語句名應是字串(針對標籤)，或者非空元組(針對非標籤型語句)。

renpy.has_label(name)

若參數name是一個程序內的合法腳本標籤(label)就返回True，否則返回False。

name

name應該是一個用於字串，用於檢查某個腳本標籤(label)是否存在。name也可以是一個非空元組，元組給定了非標籤型語句名。

renpy.invoke_in_new_context(callable, *args, **kwargs)

該函數創建了一個新的上下文(context)，並在上下文(context)中顯示調用了給定的python可調用內容(通常是函數)。當函數返回了值或者拋出異常時，主控流程會返回到原來的上下文(context)。當我們在同一個句柄(handle)中向玩家展示一些資訊(比如確認提示)，就可以調用這個函數。

某個上下文(context)包含顯示(包括界面和圖片)和音訊系統的狀態。當上下文(context)返回時，顯示和音訊狀態都會被儲存起來。

附加參數和關鍵字參數會被傳入可調用的(函數)。

使用這個函數創建的上下文(context)無法執行Ren’Py腳本。會改變Ren’Py腳本流程的函數，比如 renpy.jump()，只能在外層上下文(context)下被處理。如果你想要調用的是Ren’Py腳本而不是python函數，就應該使用 renpy.call_in_new_context() 函數。

renpy.jump_out_of_context(label)

調用該函數會引起主控流程離開當前上下文(context)，並轉換到父上下文(context)中指定的腳本標籤(label)處。

renpy.mark_label_seen(label)

在當前用戶系統內，將名為label的標籤語句設置為已執行過。

renpy.mark_label_unseen(label)

在當前用戶系統內，將名為label的標籤語句設置為未執行過。

renpy.seen_label(label)

在當前用戶系統內，名為label的標籤語句至少被執行了一次，則返回True，否則返回False。該概述常用於解鎖場景畫廊(gallery)等。

renpy.set_return_stack(stack)

設置當前返回(return)棧(stack)。返回棧是一個語句名組成的列表。

語句名可能是字串(針對標籤)或者非空元組(針對非標籤語句)。