ラベルと制御フロー

label ステートメント

label ステートメントは指定された名前にプログラム的な位置を代入します。それらは単に Ren'Py スクリプトや python 関数、スクリーンから呼び出されたり、ジャンプされたりするために存在します。

label sample1:
    "Here is 'sample1' label."

label sample2(a="default"):
    "Here is 'sample2' label."
    "a = [a]"

label ステートメントはそれに関連づけられたブロックを持つでしょう。その場合その labe ステートメントに到達すると制御はそのブロックに入り、そのブロックの終端に到達すると label ステートメントの次のステートメントに移ります。: 次のコードでは、 "origin" ラベルへジャンプしたのち、 "a, b, c" を順に表示します。

label origin:
"a"
label hasblock:
    "b"
"c"
return

二種類のラベル global と local があります。グローバルはプロジェクトファイルのすべてに渡るグローバル名前空間に置かれ、ゲーム毎に固有な名前を持つべきです。一方ローカルラベルはグローバルラベルを参照するため、異なるグローバルラベルに関連付けられていればゲーム内のいくつかのローカルラベルが同じ名前を持てます。それが宣言されたグローバルラベルのスコープ内部に論理的に配置されます。local label を宣言するには接頭辞 . を名前につけて参加するグローバルラベルの下に置いてください。例

label global_label:
    "Under a global label.."
label .local_label:
    "..resides a local one."
    jump .another_local
label .another_local:
    "And another !"
    jump .local_label

ローカルラベルはそれが宣言されたのと同じグローバルラベル内なら直接に、そうでなければグローバルとローカルネームからなるフルネームで参照出来ます。 :

label another_global:
    "Now lets jump inside a local label located somewhere else."
    jump global_label.local_name

label ステートメントは任意でパラメーターのリストを受け取ります。これらのパラメーターは PEP 570 で記述されたとおりに処理されますが、2つの例外があります :

最初に、デフォルトパラメーターの値は呼び出し時に評価されます。

第 2 に、変数のスコープは静的ではなく動的です。つまり、変数がラベルパラメータからその値を取得したときは、 return ステートメントに到達するとその変数は ( 変数の以前の値がある場合はその値に、そうでない場合は変数が存在しないように ) 戻されます。また、特定の変数を使用するステートメントが与えられた場合、その変数は、ステートメントに到達した方法に応じて、ラベルパラメーターから値を取得する場合と取得しない場合があります。これは純粋な Python コードでは不可能です。:

default a = 3

label start:
    menu:
        "Call":
            call label_with_params(5)
        "Jump":
            jump label_without_params
    jump start

label label_with_params(a):
label label_without_params:
    e "a = [a]" # displays 5 or 3 depending on what path was taken
    return

基本的にジャンプや前のステートメントから到達するラベルのパラメーターは無効です。パラメーターつきラベルの例として、 call statement を参照してください。

jump ステートメント

jump ステートメントを使用して指定のラベルに制御を移します。

expression キーワードがあればそれに続く式が評価され、算出された文字列がジャンプ先のラベル名に使用されます。 expression キーワードがなければジャンプ先のラベル名は明示的に指定されなければなりません。

ローカルラベル名は expression と一緒に渡すか、 expression なしでグローバルラベルの接頭辞("global_label.local_label") またはドット( . )をつけて (".local_label") 渡せます。

call とは異なり、jump は次のステートメントをスタックにプッシュしません。このため、ジャンプ元に戻る方法はありません。:

label loop_start:

    e "Oh no! It looks like we're trapped in an infinite loop."

    jump loop_start

call ステートメント

call ステートメントを使用して指定のラベルに制御を移します。これは同時に次のステートメントをコールスタックにプッシュし、 return ステートメントで制御を call ステートメントの次のステートメントに返せるようにします。

expression キーワードが与えられると、それに続く式が評価され、結果の文字列をラベルの名前として呼び出します。 expression キーワードが与えられない場合は、呼び出すラベルの名前を明示的に指定する必要があります。

ローカルラベル名は expression と一緒に渡すか、 expression なしでグローバルラベルの接頭辞("global_label.local_label") またはドット( . )をつけて (".local_label") 渡せます。

オプションである from 節が与えられていれば、指定された名前のラベルステートメントをその call ステートメントの直後に続くステートメントとします。ラベルの明示はコールスタックを保存したゲームデータがスクリプトを変更した後にロードされても適切な場所に返れるようにします。

call ステートメントには引数も受け取られ、それらは PEP 448 に記述されたとおりに処理されます。

引数リストつきの call expression を使用するには pass キーワードが式と引数リストの間に入らなければなりません。そうでなければ引数リストは call ステートメントではなく式の一部と解釈されます。

label start:

    e "First, we will call a subroutine."

    call subroutine

    call subroutine(2)

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

    return

# ...

label subroutine(count=1):

    e "I came here [count] time(s)."
    e "Next, we will return from the subroutine."

    return

警告

後でゲームの更新を公開するつもりならば、各 call ステートメントに対して from 節なしでゲームを公開するのは危険です。そのような節が追加されていないと、 その``call`` を含むファイルを編集すると呼び出されたラベル内で作成されたセーブが壊れる可能性があります。

"Add from clauses to calls" オプションを使用して、ゲームの配布物をビルドするときにその問題を解決できます。

return ステートメント

return ステートメントはコールスタックの一番上のステートメントをポップし、制御をそのステートメントに移します。コールスタックが空の場合、return ステートメントは Ren'Py をリセットしてメインメニューに戻します。

任意の式が return に指定されると、それは評価され、その結果が _return 変数に保存されます。この変数は各コンテキストに対して動的スコープに属します。

特別なラベル

以下のラベルは Ren'Py 本体で使用されます。 :

start

デフォルトでは Ren'Py はゲーム開始時にこのラベルにジャンプします。

quit

存在すればこのラベルはユーザーがゲーム終了時に新しいコンテキストで呼び出されます。

after_load

このラベルがあれば、ゲームのロード時に呼び出されます。ゲームが更新されたときにデータを修正するために使用できます。このラベルでデータを変更するなら、 renpy.block_rollback() を呼び出してプレーヤーがロード位置を越えてロールバックしてもこれらの変更が元に戻らないようにする必要があります。

splashscreen

存在すればこのラベルはゲームが起動されるたときにメインメニューより前に呼び出されます。 スプラッシュスクリーン追加 も参照してください。

before_main_menu

存在すればこのラベルはメインメニューより前に呼び出されます。メインメニューを用意、例えばバックグラウンドでムービーを再生するような特別な場合に使用されます。

main_menu

もし存在すればこのラベルはメインメニューの代わりに呼び出されます。制御を返すと Ren'Py は start ラベルからゲームを開始します。例えば以下のコードではメインメニューを表示せずに即座にゲームを開始します。

label main_menu:
    return

after_warp

存在すればこのラベルはワープ後にワープ先のステートメントが実行される前に呼び出されます。 行ワープ を参照してください。

hide_windows

存在すればこのラベルはプレイヤーが右クリックや H キーででウィンドウを非表示したときに呼び出されます。これが True を返せば、その非表示は (非表示が既に実行された後) キャンセルされ、そうで無ければその非表示が続きます。

ラベルと制御フロー関数

renpy.call_stack_depth()

現在のコンテキストのコールスタックの深さ、つまり呼び出し先から返らないでいるか、コールスタックからポップされた呼び出しの数を返します。

renpy.dynamic(*variables, **kwargs)

これには 1つ以上の変数名が引数として指定できます。これによりそれらの変数を動的に現在の呼び出しに対するスコープにします。その呼び出しが返ると、変数はこの関数が呼び出されたときの値にリセットされます。

名前つきの store 内の変数がサポートされます。

変数はキーワード引数として渡され、引数の値はその変数名に代入されました。

呼び出し例

$ renpy.dynamic("x", "y", "z")
$ renpy.dynamic("mystore.serial_number")
$ renpy.dynamic(players=2, score=0)

renpy.get_all_labels()

ライブラリー内部で使用するために定義されたラベルを含め、プログラムで定義されたすべてのラベルを返します。

renpy.get_return_stack()

現在のリターンスタックのリストを返します。リターンスタックはステートメント名のリストです。

ステートメント名は文字列 (ラベル) か不明瞭なタプル ( ラベルのないステートメント ) です。

renpy.has_label(name)

name がそのプログラム内での正しいラベルなら True を、そうでなければ False を返します。

name

ラベルの存在をチェックするためには文字列であるべきです。ラベルのないステートメントの名前を指定する不明瞭なタプルも可能です。

renpy.mark_label_seen(label)

その名前のラベルを現在のユーザーがすでに実行しているものとしてマークします。

renpy.mark_label_unseen(label)

その名前のラベルを現在のユーザーではまだ実行していないものとしてマークします。

renpy.pop_call()

元の場所には戻らずにコールスタックから現在の呼び出しを捨てます。Ren'Py の return ステートメントと同じように、 dynamic 変数の値も戻します。

これは呼び出されたラベルからその呼び出し元に返らないときに利用出来ます。

renpy.seen_label(label)

その名前のラベルが現在のユーザーに一度でも実行されていると True が、そうでなければ False が返されます。これは例えばシーンギャラリーをアンロックするために使用出来ます。

renpy.set_return_stack(stack)

現在のリターンスタックを設定します。リターンスタックはステートメント名のリストです。

ステートメント名は文字列 (ラベル) か不明瞭なタプル ( ラベルのないステートメント ) です。

最も一般的な使い方は、次のように使うことです

renpy.set_return_stack([])

リターンスタックをクリアします。

コンテキスト

コンテキストは、 Ren'Py がゲームの状態の変更可能な物や保存可能な物を管理するために内部的に使用します。コンテキストには以下のものがあります :

• 現在実行中のRen'Pyのステートメント

• 上述のように、コールスタックと renpy.dynamic() によって作成された動的変数の名前と以前の値を返します

• 現在表示されている画像（およびその属性や適用されている transform などの情報）

• 表示されている screen とその中の変数

• 再生中またはキューされている音声

ほとんどの場合、プレイ中にコンテキストは1つしかなく、これらの要素のインスタンスはそれぞれ1つしか存在しません。これはメインメニューやゲームメニューに入るときに変化します。上記のすべてが変更され可能性があり、メニューコンテキストを出るときに元に戻ります。これらの変化のいくつかはコンテキストに入るとスクリーンレイヤーがクリアされるように自動で変更されます。

Ren'Py は リプレイ や hiding interface のときにも新しいコンテキストを作成します。

screen language によりコンテキストを作る必要性は顕著に減りました。

ロールバックは基本コンテキストでのみ有効であり（つまり、コンテキストが1つしかない場合）、基本コンテキストのみが保存されます。このためにゲームメニューでは別のコンテキストを使用します。

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

このコードは新しいコンテキストを作成し、新しいコンテキストでそのラベルからコードを実行します。ロールバックは新しいコンテキストでは無効化され、セーブ/ロードは一番上のコンテキストで行われます。

これを使用してインタラクション中に 2 つ目のインタラクションを開始します。

これは任意のキーワード引数を取ります。

_clear_layers

True (デフォルト)の場合、新しいインタラクションが開始される前にレイヤーがクリアされます。 False の場合、レイヤーはクリアされません。リストの場合、リスト内のレイヤーのみがクリアされます。

renpy.context()

現在のコンテキストに対してユニークなオブジェクトを返します。新しいコンテキストに入るとそのオブジェクトはコピーされますが、コピーへの変更はオリジナルに影響を与えません。

オブジェクトは保存され、ロールバックに参加します。

renpy.context_dynamic(*variables)

1つ以上の変数名をこれの引数として指定できます。これによりそれらの変数を動的に現在の呼び出しに対するスコープにします。前のコンテキストに帰ると、変数はこの関数が呼び出されたときの値にリセットされます。

名前つきの store 内の変数がサポートされます。

呼び出し例

$ renpy.context_dynamic("x", "y", "z")
$ renpy.context_dynamic("mystore.serial_number")

renpy.context_nesting_level()

現在のコンテキストのネストレベルを返します。これは (セーブロード、ロールバックされる) 最も外側のコンテキストに対しては 0 で、メニューや回想のような他のコンテキストでは 0 ではありません。

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

新しいコンテキストを作成し、指定された python callable(関数)をそのコンテキストで実行します。その関数が結果を返すか例外を出力すると、制御は元のコンテキストに戻ります。一般的に、(確認プロンプトのように)イベントハンドラー内部から、プレイヤーに情報を表示する必要のある python 関数を呼び出すために使用されます。

追加の引数とキーワード引数はその呼び出し可能オブジェクトに渡されます。

この関数で作成されたコンテキストは Ren'Py スクリプトを実行できません。 renpy.jump() のような Ren'Py スクリプトの流れを変える変更をする関数はコンテキスト外で扱われます。 Python 関数ではなく Ren'Py スクリプトを呼び出したいなら、 renpy.call_in_new_context() を代わりに使ってください。

これは任意のキーワード引数を取ります。

_clear_layers

True (デフォルト)の場合、新しいインタラクションが開始される前にレイヤーがクリアされます。 False の場合、レイヤーはクリアされません。リストの場合、リスト内のレイヤーのみがクリアされます。

renpy.jump_out_of_context(label)

現在のコンテキストを終了し、親のコンテキストで指定されたラベルに制御を移動します。

renpy.reset_all_contexts()

これにより、すべてのコンテキストがコンテキストスタックからポップされ、動的変数がリセットされます。これが終わると、新しいコンテキストが作成され、現在のステートメントは終了し、次のステートメントからゲームが続行されます。これによりデータと開始位置を除いて Ren'Py は起動時の状態に戻ります。

これにより、表示されている画像、再生中の音楽など、ゲームに関するすべてをゲームが最初から開始したかのようにリセットできます。

Ren'Py を完全にリセットするため、この関数は現在のステートメントを即座に終了します。

これは主に after_load ラベルでの使用を想定しており、ゲームを開始時の状態に戻せます。その後、シーンや音楽などを再構築して続行したいラベルにジャンプできます。