スクリーンとスクリーン言語 link

Ren'Py のゲームを見ると、ゲームを画像とユーザーインターフェイスの2つの部分に分割できることに気づくでしょう。画像は scene、show、hide ステートメントを使ってユーザーに表示し、一般には進行中のストーリーの一部となっています。それ以外の部分はユーザーインターフェイスの一部で、スクリーンを使ってカスタマイズします。

スクリーンは4つの方法で表示することができます:

  • スクリプトのステートメントが実行されるとき、暗黙的に表示する。例えば、say ステートメントが事項されると、 say スクリーンが表示されます。

  • 自動的に表示する。例えば、Ren'Py はゲーム開始時や、ユーザーがメインメニューに戻るとき、 main_menu スクリーンを表示します。

  • ボタン、マウスのボタン、キーボードのキーによるアクションで表示する。デフォルトでは、ユーザーが右クリックするか、エスケープキーが押された時に save スクリーンが表示されます。他にも、スクリーン上にボタンを定義して save スクリーンを表示することも可能です。

  • 明示的に、ステートメントを使ってスクリーンを表示する。

一度に複数のスクリーンを表示できます。

スクリーンには主に2つの機能があります。1つはユーザーに情報を示すことです。情報はテキスト、バー、画像を使って示すことができます。ゲームのプレイにおいて、情報のいくつかをこのような決まりのもとで表示することは重要です。 say スクリーンで例を挙げると、これはキャラクター名と彼女が話している内容を含んだダイアローグをユーザーに表示するために使用されます。

他に、スクリーンはユーザーからの入力を受け付けてゲームに反映することができます。ボタンやバーを使うとアクションを起こしたり値を調整したりできます。Ren'Py には事前に定義されているアクションのプールがあり、ゲームを進められるようにしたり、設定を調整したり、ゲームをロード・セーブしたり、その他多数のアクションを発生させたりできます。ゲーム製作者も新しいアクションを Python で書くことができます。

スクリーンは、ゲームがインタラクションを開始した時、及びインタラクションが再開される度に更新されます。

スクリーンのコードはスクリーン外への副作用を起こしてはいけません。 Ren'Py はスクリーンが最初に表示される前に画像予測処理の一部として必要なら何度もスクリーンのコードを実行します。結果としてスクリーンのコードが副作用を持つなら、それが何回実行されるかはわかりません。

スクリーンはそれに関連付けられたスコープを持ち、変数に値を与えます。スクリーンから変数にアクセスされると最初にそのスコープ内を参照し、次にグローバルスコープを参照します。

スクリーン言語 link

スクリーン言語はほとんどが表示するスクリーンを宣言することに使用され、新しい displayable の宣言、スクリーンへの displayable の追加、ステートメントを制御するステートメントで構成されます。

ここにスクリーンの例があります。

screen say(who, what):
    window id "window":
        vbox:
            spacing 10

            text who id "who"
            text what id "what"

この最初の行は screen ステートメントで、スクリーンを宣言するために使用される Ren'Py ステートメントです。スクリーンの名前は say なので、これは台詞を表示するために使用されるスクリーンです。 2 つの引数 who, what を取ります。

このスクリーンには「 window 」の id を持つウィンドウがあります。このウィンドウは縦長の箱を持ち、その中に 10 ピクセルの空白を含みます。さらにその箱には二つのテキスト用の領域があり、一つは話し手の名前、もう一つは話している内容です。

スクリーン言語の構文 link

ほとんどのスクリーン言語は共通の構文を持ちます。 ( 制御用ステートメントのいくつかは違う構文を持ちますが ) ステートメントはステートメントを導入するキーワードで行の最初から始まります。

ステートメントがパラメーターを取るなら、キーワードの直後に続きます。パラメーターはスペースで区切られた単純式で、そうでないなら記載します。

位置パラメーターの後にはプロパティーリストが続きます。プロパティーはプロパティーの名前とそれに続くそのプロパティーの値で構成されます。プロパティーの値は特に記載がなければ単純式です。プロパティーリストはスペースで区切られた一連のプロパティーです。

ステートメントがコロン (:) で終るとその後にブロックが続きます。ブロックの各行は以下の二つのどちらかです。

  • プロパティーリスト

  • スクリーン言語のステートメント

スクリーン・ステートメント link

screen ステートメントは新しいスクリーンを宣言するための Ren'Py のスクリプト言語の一つで、スクリーン言語共通の文法で解釈されます。

一つのパラメーターを取り、それはスクリーンの名前です。これは名前であって、式ではありません。以下のプロパティーも取ります。 :

modal

True ならそのスクリーンはモーダルです。モーダルなスクリーンはデフォルトのキーマップを除いて、ユーザーがその下にある displayable に作用できないようにします。

tag

式ではなく名前として解釈されます。これはこのスクリーンと関連づけられるタグを指定します。スクリーンの表示は同じタグの他のスクリーンを置き換えます。これは一つのコンテキストには同時に一つだけメニューのスクリーンが表示されることを保証するために使用されます。

zorder

これはスクリーンがどれぐらいユーザーに近いかを制御します。数字が大きいほどスクリーンはユーザーの近くに表示されます。デフォルトでは 0 です。

variant

与えられるならこれは定義されるスクリーンバージョン名の文字列または文字列のリストです。 スクリーンバージョン を参照してください。

style_prefix
A string that's used to provide a prefix for the style for the children of this screen, as described below.
screen hello_world():
     tag example
     zorder 1
     modal False

     text "Hello, World."

スクリーンは引数もとれます。

screen center_text(s, size=42):
     text s size size

ユーザーインターフェイス・ステートメント link

ユーザーインターフェイスステートメントは displayable を作成し、それをスクリーンか、これを含めるdisplayable に追加します。ユーザーに情報を表示し、ゲームに作用したり、ゲームが様々なイベントに反応できるようにします。

すべてのユーザーインターフェイスステートメントは以下の共通のプロパティーを取ります。 :

at

変換または変換のリストで、この displayable に適用されます。もしこれが与えられ、直接スクリーンに加えられていたら show,hide,replace やその他のイベントが変換に送られます。

例えば vbox に変換が適用されて、直接スクリーンに追加されているとイベントはその変換に送られます。しかしある変換が vbox に追加されているテキストボタンに適用されていると、この第二の変換にはイベントが送られません。

default

True を与えると displayable はデフォルトでフォーカスを持つようになります。一つの displayable のみがこれを持つべきです。

id

ユーザーインターフェイスステートメント用の識別記号です。スクリーンが表示されると適切な値が与えられた id を持つ displayable に提供されます。いくつかのスクリーンは与えられた id を持つ displayable の作成を必要とします。

デフォルトでは id は自動的に生成されます。

style

この displayable に適用されるスタイルの名前です。これは名前の文字列か、 style オブジェクトです。そのスタイルはスタイルプロパティーにデフォルトの値を与えます。

style_prefix

この displayable と、その子がより限定的なスタイルやスタイル接頭辞を持っていなければ、そのすべての子のスタイルに接頭辞を与えます

スタイル名はスタイル接頭辞とアンダースコア、スタイル接尾辞を繋げて作られる。スタイル接尾辞は style_suffix を使用して指定するか、displayableに決定されます。

例えば vbox がスタイル接頭辞「 pref 」を持っていると、 vbox にはスタイル「 pref_vbox 」が与えられます。より限定的なスタイルやスタイル接頭辞が与えられていなければ、その vbox 内のボタンはスタイル「 pref_button 」を持ちます。

このようにアクセスされるスタイルは、もしなければ作成されます。接頭辞を None に設定するとこの displayable とその子から接頭辞が取り除かれます。

style_group

style_prefix のエイリアスで、以前のコードで使用されます。

style_suffix

style_prefix と結合してスタイル名になる接尾辞を指定します。これが "small_button" でスタイル接頭辞が "pref" なら、スタイルは "pref_small_button" が使用されます。

スタイル接頭辞がなければ、これはスタイル名が直接使用されます。スタイル接尾辞は単独の displayable のみに適用され、 displayable の子には適用されません。

focus

文字列か整数を受け取って displayable にフォーカス用の名前を与えます。Ren'Py はインタラクションの開始時にフォーカスを与える displayable を決定するとき、フォーカスの名前の間に構造的な類似点を探します。例えばある box にフォーカス名が与えられて、その box の三つ目のボタンがインタラクションの最後にフォーカスを所得すると、同じフォーカス名を持つ box の三つ目のボタンが次のインタラクションの開始時にハイライトされるます。

多くのユーザーインターフェイスステートメントはスタイルプロパティーや変換プロパティーのクラスを取ります。これらのプロパティーはそれに関連づけられたスタイルの接頭辞を持ちます。例えばテキストに hover_size プロパティーが与えられるとそれはテキストの上にマウスがあるときのテキストの大きさを設定します

Add link

画像やその他の displayable をスクリーンに追加します。これは任意で 変換プロパティー を取ります。少なくとも一つ変換プロパティーが与えられると、その画像に適用する変換が作成されプロパティーはその変換に渡されます。

displayable が None ならスクリーンには何も追加されません。

これは子を取りません。

screen add_test():
    add "logo.png" xalign 1.0 yalign 0.0

Bar link

データを閲覧したり調整するための水平方向のバーを作成します。以下のプロパティーを取ります。

value

バーの現在の値。これは bar value オブジェクトか数字です。

range

バーの最大値です。これは value が数字なら必要です。

adjustment

このバーを調整する ui.adjustment() オブジェクトです。

changed

与えるならこれは python 関数であるべきです。関数は adjustmentが変更されるとその adjustment の value を引数に呼び出されます。

hovered

バーがフォーカスを所得したときのアクションです。

unhovered

バーがフォーカスを失うときのアクションです。

valueadjustment のどちらかは与えられなければなりません。さらにこの関数は以下を取ります。 :

これは子は取りません。

screen volume_controls():
    frame:
        has vbox

        bar value Preference("sound volume")
        bar value Preference("music volume")
        bar value Preference("voice volume")

Button link

スクリーンのあるエリアを、アクションを実行するために押せるようにします。ボタンはパラメーターを取らず以下のプロパティーを取ります。

action

ボタンが押されると実行するアクションです。ボタンはクリックされるか、プレイヤーが選択してキーボードのエンターを押すかするとアクティベートされます。これは`sensitive` がなければボタンが有効かどうかの、 selected がなければ選択されているかどうかの制御もします。

alternate

ボタンが代替方法で押されると実行されるアクションです。代替方法はプレイヤーがマウスベースのプラットフォームでボタン上で右クリックするか、タッチベースのプラットフォームで長押しすると発生します。

hovered

ボタンがフォーカスを所得するときのアクションです。

unhovered

ボタンがフォーカスを失うときのアクションです。

selected

ボタンが選択されているかどうかを決定する式です。この式はインテラクション毎に少なくとも一回評価されます。 与えられなければ、アクションが選択状態決定に使用されます。

sensitive

ボタンが有効かどうかを決定する式です。この式はインテラクション毎に少なくとも一回評価されます。 与えられなければ、アクションが有効無効決定に使用されます。

keysym

押すとこのボタンのアクションを実行するキーボードのキーを表わす keysym の文字列です。

alternate_keysym

押すとこのボタンの代替アクションを実行するキーボードのキーを表わす keysym の文字列です。

以下も取ります。 :

これは子を一つ取ります。 ゼロまたは二つ以上の子が与えられるとそれらは暗黙のうちに fixed に追加され、それがボタンに追加されます。

Fixed link

これは子を追加可能な領域を作成します。デフォルトでは fixed は利用可能な領域をすべて使用しますが、 xmaximumymaximum プロパティーを使用すればこれを変更できます。

子はそれぞれの位置スタイルプロパティーに従って配置されます。適切に位置が指定されていないと、これらは重なり合ってしまうかもしれません。

fixed ステートメントはパラメーターは取らず、以下のプロパティーを取ります。 :

これは fixed に追加されるすべての子を受け取ります。

fixed displayable を明示的に作成する必要はほとんどありません。各スクリーンは fixed displayable に含まれており、多くのスクリーン言語は二つ以上の子を持つと自動的に fixed を生成します。

screen ask_are_you_sure:
    fixed:
         text "Are you sure?" xalign 0.5 yalign 0.3
         textbutton "Yes" xalign 0.33 yalign 0.5 action Return(True)
         textbutton "No" xalign 0.66 yalign 0.5 action Return(False)

Frame link

frame はユーザーインターフェイスを表示するための背景を含むウィンドウで、以下のプロパティーを取ります。 :

これは一つの子を取ります。 0 か 2 以上の子が与えられると、それらを含めるために fixed が作成されます。

screen test_frame():
    frame:
        xpadding 10
        ypadding 10
        xalign 0.5
        yalign 0.5

        vbox:
            text "Display"
            null height 10
            textbutton "Fullscreen" action Preference("display", "fullscreen")
            textbutton "Window" action Preference("display", "window")

Grid link

これはその子をグリッドに表示します。各子には最大のサイズの子と同じサイズの領域が与えられます。

二つのパラメーターを取ります。最初の要素はグリッドの縦の列の数で、第二要素はグリッドの横の列の数です。以下のプロパティーを取ります。 :

transpose

デフォルトは False で、横の列が縦の列より先に埋められます。 True なら立ての列が横の列より先に埋められます。

spacing

グリッドの縦横の列の間のスペース

以下も取ります。 :

これは縦掛ける横だけの子を与えられる必要があり、違う数の子が与えられるとエラーになります。

screen grid_test:
     grid 2 3:
         text "Top-Left"
         text "Top-Right"

         text "Center-Left"
         text "Center-Right"

         text "Bottom-Left"
         text "Bottom-Right"

Hbox link

これはその子を透明な横長の箱に左から見に並べて表示します。これはパラメーターを取らず、以下のプロパティーを取ります。 :

UI displayable の子はボックスに追加されます。

screen hbox_text():
    hbox:
         text "Left"
         text "Right"

Imagebutton link

その上にマウスがあると状態が変化する画像で構成されるボタンを作成します。これはパラメーターを取らず、以下のプロパティーを取ります。 :

auto

このボタンに使用する画像を自動的に定義するために使用されます。これは %s を含む文字列であるべきです。これが与えられて、画像のプロパティーの一部が省略されていると %s をそのプロパティーの名前で置き換えて、その値をそのプロパティーのデフォルトとして使用します。

例えば auto が "button_%s.png" で idle が省略されると、 idle はデフォルトで "button_idle.png" になります。同様に auto が "button %s" なら button idle 画像が使用されます。

auto の動作は config.imagemap_auto_function を変更することで動作します。

insensitive

ボタンが無効の時使用される画像

idle

ボタンがフォーカスを持っていない時使用される画像

hover

ボタンがフォーカスを持っている時使用される画像

selected_idle

ボタンが選択されアイドル状態の時使用される画像

selected_hover

ボタンが選択されフォーカスを持っている状態の時使用される画像

action

ボタンが押されると実行されるアクションです。これは`sensitive` がなければボタンが有効かどうかの、 selected がなければ選択されているかどうかの制御もします。

alternate

ボタンが代替方法で押されると実行されるアクションです。代替方法はプレイヤーがマウスベースのプラットフォームでボタン上で右クリックするか、タッチベースのプラットフォームで長押しすると発生します。

hovered

ボタンがフォーカスを所得するときのアクションです。

unhovered

ボタンがフォーカスを失うときのアクションです。

selected

ボタンが選択されているかどうかを決定する式です。この式はインテラクション毎に少なくとも一回評価されます。 与えられなければ、アクションが選択状態決定に使用されます。

sensitive

ボタンが有効かどうかを決定する式です。この式はインテラクション毎に少なくとも一回評価されます。 与えられなければ、アクションが有効無効決定に使用されます。

keysym

押すとこのボタンのアクションを実行するキーボードのキーを表わす keysym の文字列です。

alternate_keysym

押すとこのボタンの代替アクションを実行するキーボードのキーを表わす keysym の文字列です。

以下も取ります。 :

これは子を取りません。

screen gui_game_menu():
     vbox xalign 1.0 yalign 1.0:
          imagebutton auto "save_%s.png" action ShowMenu('save')
          imagebutton auto "prefs_%s.png" action ShowMenu('preferences')
          imagebutton auto "skip_%s.png" action Skip()
          imagebutton auto "afm_%s.png" action Preference("auto-forward mode", "toggle")

Input link

テキスト入力をする領域を作成し、ユーザーがテキストを入力できるようにします。ユーザーが Enter を押すと、テキストがインタラクションから返されます (call screen からスクリーンを呼び出したとき、 _return 変数に結果が代入されます) 。

input ステートメントはパラメーターを取らず、以下のプロパティーを取ります。 :

value

この input が使用する input value オブジェクトです。 InputValue オブジェクトはデフォルト値、テキスト変更、エンター押下時の動作、テキストがデフォルトで変更可能かどうかを決定します。

これは defaultchanged と同時に指定してはいけません。

default

入力されるデフォルトのテキストです。

length

入力されるテキストの最大の長さです。

pixel_width

入力の最大ピクセル幅です。入力した文字がこの幅を越えると、そのキー入力は無視されます。

allow

入力できる文字を含む文字列です。 (デフォルトではすべての文字が許可されます。 )

exclude

入力出来ない文字を含む文字列です。 (デフォルトでは「{}」です。 )

prefix

ユーザーが入力したテキストの先頭に追加される文字列です。

suffix

ユーザーが入力したテキストの末尾に追加される文字列です。

changed

ユーザーが入力した文字列を引数に、文字列が変更したときに呼ばれる python 関数です。

以下も取ります。 :

これは子を取りません。

screen input_screen():
    window:
        has vbox

        text "Enter your name."
        input default "Joseph P. Blow, ESQ."

Key link

これはキーが押されるとアクションを実行するキーバインドを作成します。 キーはここではジョイスティックやマウスイベントも含む大まかな意味で使用されています。

key は一つのパラメーターを取り、それは関連づけるキーの文字列です。利用可能なキーについては キーマップのカスタマイズ の章を参照してください。これは1つのプロパティーを取ります:

action

これはキーが押されると実行されるアクションを与えます。このプロパティーは必ず必要です。

これは子を取りません。

screen keymap_screen():
    key "game_menu" action ShowMenu('save')
    key "p" action ShowMenu('preferences')
    key "s" action Screenshot()

Label link

ラベルスタイルのウィンドウを作成し、その内側にテキストを置きます。同時にこの連携はフレーム内部にラベルを貼るために使用されます。

パラメーターを一つ持ち、それはラベルの文字列です。以下のプロパティーも取ります。 :

text_style

ボタンテキストに使用されるスタイルの名前です。これが与えられず、さらに style プロパティーが文字列なら、「 _text 」がその文字列に追加されてデフォルトのテキストスタイルになります。

text_-

text を接頭辞に持つその他のプロパティーは、この接頭辞を取ってテキスト displayable に渡されます。

以下も取ります。 :

子は取りません。

screen display_preference():
    frame:
        has vbox

        label "Display"
        textbutton "Fullscreen" action Preference("display", "fullscreen")
        textbutton "Window" action Preference("display", "window")

Null link

null ステートメントはスクリーンに空白の領域を挿入します。これは間を開けるために使用されます。 null ステートメントはパラメーターは取らず、以下のプロパティーを取ります。 :

width

ピクセル数での空白の幅です。

height

ピクセル数での空白の高さです。

以下も取ります。 :

子は取りません。

screen text_box():
    vbox:
         text "The title."
         null height 20
         text "This body text."

Mousearea link

マウスエリアはマウスの出入りに反応できるスクリーンの領域です。ボタンと違ってマウスエリアはフォーカスを取らないので、その内部にボタンを持つマウスエリアも可能です。 mousearea ステートメントはパラメーターを取らず、以下のプロパティーを取ります。 :

hovered

マウスエリアにマウスが入ると実行されるアクション

unhovered

マウスエリアからマウスが出ると実行されるアクション

focus_mask

focus_mask スタイルプロパティーで、 displayable か None です。displayable ならマウスがその displayable の不透明な領域上にあるときのみマウスエリアはフォーカスを持ちます。 ( displayable はユーザーには表示されません。 )

以下も取ります。 :

子は取りません。

通常 mouseare ステートメントは area スタイルプロパティーを受け取ってマウスエリアのサイズや位置を制御します。そのサイズを制御しないとマウスエリアは画面全体になり、かなり不便です。

注釈

Ren'Py のゲームはキーボードとジョイスティックでもプレイ出来るので、他の方法でもマウスエリアの機能を再現してください。

screen button_overlay():
    mousearea:
        area (0, 0, 1.0, 100)
        hovered Show("buttons", transition=dissolve)
        unhovered Hide("buttons", transition=dissolve)

screen buttons():
    hbox:
        textbutton "Save" action ShowMenu("save")
        textbutton "Prefs" action ShowMenu("preferences")
        textbutton "Skip" action Skip()
        textbutton "Auto" action Preference("auto-forward", "toggle")

label start:
    show screen button_overlay

Side link

これはグリッドの中心か端に displayable を配置します。これは一つのパラメーターを取り、それはスペースで区切られたその子を配置する場所のリストです。このリストの各要素は以下のうちの一つです。 :

'c', 't', 'b', 'l', 'r', 'tl', 'tr', 'bl', 'br'

「c」は中心、「t」は上端、「tl」は左上端、「br」は右下など

side は以下のプロパティーを取ります。 :

spacing

グリッドの縦横の列の間のスペース

side は以下の種類のプロパティーも取ります。 :

レンダリング時に、これは最初に角を、次に側面、最後に中心のサイズを決定します。角と側面は利用可能な領域を 0 としてレンダリングされるので、それらに最小のサイズを与えて ( xminimum または yminimum を使用して ) すべてが描画される保証をする必要は多分ないです。

位置リストのすべてに対応する子があるので、これは位置リストに登録されているのと同じ数の子を持たなければなりません。

screen side_test():
     side "c tl br":
          text "Center"
          text "Top-Left"
          text "Bottom-Right"

Text link

text ステートメントはテキストを表示します。これはパラメーターを一つ取り、それは表示するテキストです。以下のプロパティーも取ります。 :

子は取りません。

screen hello_world():
    text "Hello, World." size 40

Textbutton link

テキストトラベル付きのボタンを作成します。ボタンはパラメーターを一つ取り、それはボタンの一部に含むテキストです。以下のプロパティーを取ります。 :

action

ボタンが押されると実行されるアクションです。これは`sensitive` がなければボタンが有効かどうかの、 selected がなければ選択されているかどうかの制御もします。

alternate

ボタンが代替方法で押されると実行されるアクションです。代替方法はプレイヤーがマウスベースのプラットフォームでボタン上で右クリックするか、タッチベースのプラットフォームで長押しすると発生します。

hovered

ボタンがフォーカスを所得するときのアクションです。

unhovered

ボタンがフォーカスを失うときのアクションです。

selected

ボタンが選択されているかどうかを決定する式です。この式はインテラクション毎に少なくとも一回評価されます。 与えられなければ、アクションが選択状態決定に使用されます。

sensitive

ボタンが有効かどうかを決定する式です。この式はインテラクション毎に少なくとも一回評価されます。 与えられなければ、アクションが有効無効決定に使用されます。

keysym

押すとこのボタンのアクションを実行するキーボードのキーを表わす keysym の文字列です。

alternate_keysym

押すとこのボタンの代替アクションを実行するキーボードのキーを表わす keysym の文字列です。

text_style

ボタンテキストに使用されるスタイルの名前です。これが与えられず、さらに style プロパティーが文字列なら、「 _text 」がその文字列に追加されてデフォルトのテキストスタイルになります。

text_-

text を接頭辞に持つその他のプロパティーは、この接頭辞を取ってテキスト displayable に渡されます。

以下も取ります。 :

子は取りません。

screen textbutton_screen():
    vbox:
        textbutton "Wine" action Jump("wine")
        textbutton "Women" action Jump("women")
        textbutton "Song" action Jump("song")

Timer link

これは時間が来るとアクションを実行するタイマーを作成します。これは一つのパラメーターを取り、それは秒数です。以下のプロパティーも取ります。 :

action

時間が来ると実行するアクションを指定します。このプロパティーは必須です。

repeat

True ならその時間が経つ度にタイマーが繰り返し実行されます。

これは子を取りません。

screen timer_test():
    vbox:
         textbutton "Yes." action Jump("yes")
         textbutton "No." action Jump("no")

    timer 3.0 action Jump("too_slow")

Transform link

変換をその子に適用します。これはパラメーターを取らず、以下のプロパティーを取ります。 :

これは子を一つは受け取る必要があります。

Vbar link

横向きになった bar です。プロパティーは bar と同じです。

screen volume_controls():
     frame:
         has hbox

         vbar value Preference("sound volume")
         vbar value Preference("music volume")
         vbar value Preference("voice volume")

Vbox link

これはその子を透明な縦長の箱に縦に並べて表示します。これはパラメーターを取らず、以下のプロパティーを取ります。 :

UI displayable の子はボックスに追加されます。

screen vbox_test():
    vbox:
         text "Top."
         text "Bottom."

Viewport link

viewport はドラッグやマウスホイールまたはスクロールバーでスクロール可能なスクリーンの領域です。画面より大きいものを表示するために使用され、以下のプロパティーを取ります。 :

child_size

レンダリングのために子に与えられるサイズで、 (xsize, ysize) のタプルです。子が自身のサイズを算出できるとき、これは通常省略されます。どちらかの要素が None なら子のサイズが使用されます。

mousewheel

これはつぎのうちの一つです

False
To ignore the mousewheel. (The default.)
True
To scroll vertically.
"horizontal"
To scroll horizontally.
"change"
To scroll the viewport vertically, only if doing so would cause the viewport to move. If not, the mousewheel event is passed to the rest of the interface. (For example, if change is given, placing key "viewport_wheeldown" action Return() before the viewport will cause the screen to return if the viewport scrolls past the bottom.)
"horizontal-change"
Combines horizontal scrolling with change mode.
draggable

True ならマウスのドラッグで viewport をスクロール出来ます。

edgescroll

マウスが viewport の端に到達するとスクロールします。 None を設定するか、2要素か3要素のタプルを設定します :

  • タプルの最初の要素は viewport の端からのピクセル数での距離であり、その距離からエッジスクロールが開始されます。

  • 第二要素は一秒ごとに何ピクセルスクロールするかの最大値です。

  • 与えられるなら三番目の要素はスクロールのスピードをマウスポインターと端との距離に基づいて調整する関数です。関数は -0.0 から 1.0 までの範囲の数字を引数に取り、同じ範囲の数字を返すべきです。デフォルトの関数では入力をそのまま返し、端との近さに比例スクロールを加速させます。関数が入力された符号に基づき 1.0 か -1.0 を返すと一定の速度のスクロールになります。

xadjustment

ui.adjustment() は viewport の x 軸のために使用されます。省略されると新しい adjustment が作成されます。

yadjustment

ui.adjustment() は viewport の y 軸のために使用されます。省略されると新しい adjustment が作成されます。

xinitial

viewport の初期の水平位置のオフセットです。これはピクセル数の整数か、可能なオフセットの割合の小数です。

yinitial

viewport の初期の垂直位置のオフセットです。これはピクセル数の整数か、可能なオフセットの割合の小数です。

scrollbars

None でなければスクロールバーがこの viewport に追加されます。これは side レイアウトを作成し、その sideの中心に viewport を作成した viewport を置くことで動作します。 scrollbars が "horizontal" なら水平なスクロールバーが viewport の下に追加され、 scrollbars が "vertical" なら垂直なスクロールバーが viewport の右に追加されます。 scrollbars が "both" なら水平垂直両方のスクロールバーが作成されます。

scrollbars が None でなければ viewport は「side」で始まるプロパティーを受け取ります。これらは作成された side レイアウトに渡されます。

さらにこれは以下のスタイルプロパティーを取ります。 :

これは一つの子を取ります。 0 か 2 以上の子が与えられると、それらを含めるために fixed が作成されます。

viewport のスクロールバーを作成するためにはそれに id を与えて、その id を引数に XScrollValue()YScrollValue() を使用するのが最適です。

screen viewport_example():
    side "c b r":
         area (100, 100, 600, 400)

         viewport id "vp":
             draggable True

             add "washington.jpg"

         bar value XScrollValue("vp")
         vbar value YScrollValue("vp")

Vpgrid link

vpgrid (viewport grid) は viewport と grid を一つの displayable に結合します。 vpgrid は grid のように複数の子を受け取り、それらの子のレンダリングは最適化され、 viewport 内に表示されている子のみがレンダリングされます。

vpgrid はすべてのセルが同じサイズで、最初の子のサイズであると想定します。 vpgrid が誤ってレンダリングされたら、すべての子が同じサイズであるか確認してください。

vpgrid には colrows の少なくとも一つのまたは両方のプロパティーが指定されなければいけない。一つが省略されるか None なら他方か子の数から自動的に決定されます。

Vgrids は以下のプロパティーを取ります。 :

cols

グリッドの行数

rows

グリッドの列数

transpose

True なら列の前に行が埋められます。これのデフォルトは colsrows プロパティーに依存します。 cols が与えられたなら、行が列の前に埋められ、そうでなければ列が行の前に埋められます。

spacing

行間のピクセル数での空間

加えて、 vpgrid は viewport のすべてのプロパティーとグリッドのサイズまでの複数の子を受け取ります。セルを埋めるのに十分な子がなければ、いくつかのセルはレンダリングされません。

screen vpgrid_test():

    vpgrid:

        cols 2
        spacing 5
        draggable True
        mousewheel True

        scrollbars "vertical"

        # Since we have scrollbars, we have to position the side, rather
        # than the vpgrid proper.
        side_xalign 0.5

        for i in range(1, 100):

            textbutton "Button [i]":
                xysize (200, 50)
                action Return(i)

Window link

widow はゲーム内の台詞を表示するための背景を含むウィンドウのことです。これは以下のプロパティーを取ります。 :

これは一つの子を取ります。 0 か 2 以上の子が与えられると、それらを含めるために fixed が作成されます。

screen say(who, what):
    window id "window"
        vbox:
            spacing 10

            text who id "who"
            text what id "what"

Imagemap ステートメント link

スクリーン、特に視覚的なものを作成する便利な方法は imagemap を使用することです。 imagemap を作成するときに imagemap ステートメントは 6 つの画像を指定するために使用されます。hotspot と hotbar の画像はその画像の長方形の領域を切り取って、アクションと value をそれらの領域に適用するために使用されます。

ここに imagemap を使用した preferences スクリーンの例があります。

screen preferences():

    tag menu
    use navigation

    imagemap:
        auto "gui_set/gui_prefs_%s.png"

        hotspot (740, 232, 75, 73) action Preference("display", "fullscreen") alt _("Display Fullscreen")
        hotspot (832, 232, 75, 73) action Preference("display", "window") alt _("Display Window")
        hotspot (1074, 232, 75, 73) action Preference("transitions", "all") alt _("Transitions All")
        hotspot (1166, 232, 75, 73) action  Preference("transitions", "none") alt _("Transitions None")

        hotbar (736, 415, 161, 20) value Preference("music volume") alt _("Music Volume")
        hotbar (1070, 415, 161, 20) value Preference("sound volume") alt _("Sound Volume")
        hotbar (667, 535, 161, 20) value Preference("voice volume") alt _("Voice Volume")
        hotbar (1001, 535, 161, 20) value Preference("text speed") alt _("Text Speed")

Imagemap link

imagemap ステートメントは画像を指定するために使用されます。これはパラメーターは取らず、以下のプロパティーを取ります。 :

auto

この imagemap に使用する画像を自動的に定義するために使用されます。これは %s を含む文字列であるべきです。これが与えられて、画像のプロパティーの一部が省略されていると %s をそのプロパティーの名前で置き換えて、その値をそのプロパティーのデフォルトとして使用します。

例えば auto が "imagemap_%s.png" で idle が省略されると、 idle はデフォルトで "imagemap_idle.png" になります。同様に auto が "imagemap %s" なら imagemap idle 画像が使用されます。

auto の動作は config.imagemap_auto_function を変更することで動作します。

ground

hotspot や hotbar の一部ではない画像を配置するために使用される画像

insensitive

hotspot や hotbar が無効の時に使用される画像

idle

hotspot が選択されておらず、フォーカスを持たないとき、また hotbar がフォーカスを持たずバーが空のときに使用される画像

hover

hotspot が選択されておらず、フォーカスを持つとき、また hotbar がフォーカスを持ちバーが空のときに使用される画像

selected_idle

hotspot が選択され、フォーカスを持たないとき、また hotbar がフォーカスを持たずバーが満タンのときに使用される画像

selected_hover

hotspot が選択され、フォーカスを持つとき、また hotbar がフォーカスを持ちバーが満タンのときに使用される画像

alpha

これはデフォルトでは True で、 hotspot はマウスが画像の不透明な領域上にあるときだけフォーカスを持ちます。 False なら hotspot はマウスが長方形の領域上にあるとフォーカスを持ちます。

cache

これはデフォルトでは True で、 hotspot のデータはキャッシュして追加のディスク消費の代わりにパフォーマンスを改善します。

以下のプロパティーを取ります。 :

imagemap は fixed を作成し、 ( hotspot と hotbar だけでなく ) すべての子をそこに追加します。

Hotspot link

hotspot は画像で構成されるボタンです。ボタンを作成する imagemap の領域を与えるタプル (x, y, width, height) を一つのパラメーターとして受け取ります。これは以下のプロパティー取ります。 :

action

ボタンが押されると実行されるアクションです。これはボタンが有効か、選択されているかどうかの制御もします。

alternate

ボタンが代替方法で押されると実行されるアクションです。代替方法はプレイヤーがマウスベースのプラットフォームでホットスポットを右クリックするか、タッチベースのプラットフォームで長押しすると発生します。

hovered

ボタンがフォーカスを所得するときのアクションです。

unhovered

ボタンがフォーカスを失うときのアクションです。

selected

ボタンが選択されているかどうかを決定する式です。この式はインテラクション毎に少なくとも一回評価されます。 与えられなければ、アクションが選択状態決定に使用されます。

sensitive

ボタンが有効かどうかを決定する式です。この式はインテラクション毎に少なくとも一回評価されます。 与えられなければ、アクションが有効無効決定に使用されます。

keysym

押すとこのボタンのアクションを実行するキーボードのキーを表わす keysym の文字列です。

alternate_keysym

押すとこのボタンの代替アクションを実行するキーボードのキーを表わす keysym の文字列です。

以下も取ります。 :

hotspot は fixed を作成し、そこに子を追加出来るようにします。 fixed は hotspot と同じ大きさの領域を持つので、子は hotspot に対する相対距離で配置されます。

hotspot に alt スタイルプロパティーを与えることで、Ren'Py の自己発話機能が動くようになります。

Hotbar link

hotbar は画像で構成されるバーです。バーを作成する imagemap の領域を与えるタプル (x, y, width, height) を一つのパラメーターとして受け取ります。これは以下のプロパティー取ります。 :

value

バーの現在の値。これは bar value オブジェクトか数字です。

range

バーの最大値です。これは value が数字なら必要です。

adjustment

このバーを調整する ui.adjustment() オブジェクトです。

valueadjustment のどちらかは与えられなければなりません。さらにこの関数は以下を取ります。 :

これは子は取りません。

hotbar に alt スタイルプロパティーを与えることで、Ren'Py の自己発話機能が動くようになります。

Advanced Displayables link

よく使用されるステートメントに加えてスクリーン言語は高度な displayable に対応するステートメントを持ちます。displayable とステートメントの対応は単純です。displayable の位置引数はそのステートメントの位置パラメーターになり、キーワード引数と、関連するスタイルプロパティーはスクリーン言語のプロパティーになります。

高度な displayable のステートメント :

drag

Drag クラスを作成します。 drag には任意の子が与えられるか、または child スタイルプロパティーを使用して子や、それがフォーカスを所得した場合のバージョンが提供されます。drag は focus_mask スタイルプロパティーも取れます。

draggroup

DragGroup クラスを作成します。DragGroup はその子として 0 以上の drag を持ちます。

Has ステートメント link

has ステートメントは fixed の代わりに子を一つだけ受け取るステートメントのために使用するコンテナを指定できるようにします。 has ステートメントはおそらく一つの子を受け取るステートメントの内部でのみ使用されるでしょう。キーワード引数 has の (同じ行の) 後にはもう一つのステートメントが続き、それは一つ以上の子を受け取るコンテナの displayable を作成するステートメントでなければなりません。

has ステートメントはそれを含むブロックの解釈を変更しします。そのブロックで作成された子の displayable は親の displayable ではなくそのコンテナに追加されます。親の displayable に対するキーワード引数は has ステートメントの後は許可されません。複数の has ステートメントが同じブロックで使用可能です。

has ステートメントは以下のステートメントの子として提供されます。

  • button
  • frame
  • window

has ステートメントには以下のステートメントが入れ物として与えられます。

  • fixed
  • grid
  • hbox
  • side
  • vbox
screen volume_controls():
     frame:
         has vbox

         bar value Preference("sound volume")
         bar value Preference("music volume")
         bar value Preference("voice volume")

制御用のステートメント link

スクリーン言語は条件実行や反復、他のスクリーンを含んだり、イベントによるアクションの実行や任意の python コードの実行のために制御用のステートメントを含みます。

Default link

default ステートメントはそのスクリーンが最初の 1 つなら変数のデフォルト値を設定します。 SetScreenVariable()

default ステートメントは変数がスクリーンの引数として渡されなかったり、 use ステートメントを使用してそのスクリーンを呼び出しているスクリーンから継承されなければ変数のデフォルトの値を設定します。

screen scheduler():
    default club = None
    vbox:
         text "What would you like to do?"
         textbutton "Art Club" action SetScreenVariable("club", "art")
         textbutton "Writing Club" action SetScreenVariable("club", "writing")

         if club:
             textbutton "Select" action Return(club)

For link

for ステートメントは同様の python ステートメントと等価ですが、else節をサポートしていません。変数同様にタプルもサポートしています。

$ numerals = [ 'I', 'II', 'III', 'IV', 'V' ]

screen five_buttons():
    vbox:
        for i, numeral in enumerate(numerals):
            textbutton numeral action Return(i + 1)

If link

スクリーン言語の if ステートメントは Python/Ren'Py の if ステートメントと同様です。 if, elif, else 節をサポートしています。

screen skipping_indicator():
    if config.skipping:
         text "Skipping."
    else:
         text "Not Skipping."

On link

on ステートメントはイベントによってスクリーンがアクションを実行できるようにします。一つのパラメーターを取り、それはイベントの名前です。これは以下のうち一つであるべきです。 :

  • "show"
  • "hide"
  • "replace"
  • "replaced"

イベント時に実行するアクションを与えるプロパティーを取ります。

screen preferences():
    frame:
        has hbox

        text "Display"
        textbutton "Fullscreen" action Preferences("display", "fullscreen")
        textbutton "Window" action Preferences("display", "window")

    on "show" action Show("navigation")
    on "hide" action Hide("navigation")

Use link

use ステートメントはスクリーンに他のスクリーンを含めるようにします。 use ステートメントは使用するスクリーンの名前を受け取ります。これには任意で括弧で囲まれた引数が続きます。

使用したスクリーンにパラメーターがあれば、引数をそれらのパラメーターに代入した結果でそのスコープは初期化されます。そうでなければ現在のスクリーンのスコープが渡され、現在のスクリーンに渡されたキーワード引数で更新されます。

screen file_slot(slot):
    button:
        action FileAction(slot)

        has hbox

        add FileScreenshot(slot)
        vbox:
            text FileTime(slot, empty="Empty Slot.")
            text FileSaveName(slot)


 screen save():
     grid 2 5:
         for i in range(1, 11):
              use file_slot(i)

use ステートメントは必要ならプロパティー id を引数リストの後に 1 つ取れます。このスクリーンは同じタグを持つ 2 つのスクリーンが同じスクリーンを使用するときのみ便利です。この場合、あるスクリーンが別のスクリーンを置き換えると、使用されたスクリーンの状態は以前のスクリーンから新しいスクリーンへ譲渡されます。

transform t1():
    xpos 150
    linear 1.0 xpos 0

screen common():
    text "Test" at t1

screen s1():
    tag s
    use common id "common"
    text "s1" ypos 100

screen s2():
    tag s
    use common id "common"
    text "s2" ypos 100

label start:
    show screen s1
    pause
    show screen s2
    pause
    return

Use と Transclude link

use ステートメントはスクリーン言語ステートメントのブロックも受け取れます。ブロック指定時に使用されるスクリーンには transclude ステートメントがあるでしょう。 transclude ステートメントは use ステートメントのブロック内にあるステートメントで置き換えられます。

これによりスクリーンを使用する再利用可能なレイアウトが定義出来るようになります。例えば次のスクリーン

screen movable_frame(pos):
    drag:
        pos pos

        frame:
            background Frame("movable_frame.png", 10, 10)
            top_padding 20

            transclude

は他の要素をラップする再利用可能な要素で、以下のように使用します。

screen test:
    use movable_frame((0, 0)):
        text "You can drag me."

    use movable_frame((0, 100)):
        vbox:
            text "You can drag me too."
            textbutton "Got it!" action Return(True)

use と transclude は :ref:` ユーザー定義スクリーン言語ステートメント <creator-defined-sl>` に基づいて組み立てます。

Python link

スクリーン言語には python コードを実行する一行または複数行の python ステートメントも含まれます。このコードはそのスクリーンのスコープで実行します。

python コードはスクリーンの外への副作用を起こしてはいけません。 Ren'Py はスクリーンが最初に表示される前に画像予測処理の一部として必要なら何度もスクリーンのコードを実行します。結果としてスクリーンのコードが副作用を持つなら、それが何回実行されるかはわかりません。

screen python_screen:
    python:
        test_name = "Test %d" % test_number

    text test_name

    $ test_label = "test_%d" % test_label

    textbutton "Run Test" action Jump(test_label)

Showif Statement link

showif ステートメントは条件をとります。条件が Trueならその子を表示し、 False ならその子を非表示にします。 showif の子が変換を持つなら、子に ATL イベントを送り、表示、非表示処理を管理して Ren'Py がアニメーションで表示、非表示するようにします。

複数の showif ステートメントは if ステートメント同様 1 つの showif/elif/else 構造に纏められます。** if ステートメントとは違い、条件が False であっても python コードを含むそのブロックを showif はすべて実行します。これは showif ステートメントが非表示される子を作成する必要があるためです。 **

showif は 3 つのイベントをその子に送ります。

appear

スクリーンが最初に表示されたときで、条件が True なら送られ、即座に子を表示します。

show

条件が False から True に変わると送られます。

hide

条件が True から False に変わると送られます。

これらの目的のため、 elif 節の条件はそれ以前の条件が True なら常に False で、すべての条件が False なら else 節だけが True になります。

transform cd_transform:
    # This is run before appear, show, or hide.
    xalign 0.5 yalign 0.5 alpha 0.0

    on appear:
        alpha 1.0
    on show:
        zoom .75
        linear .25 zoom 1.0 alpha 1.0
    on hide:
        linear .25 zoom 1.25 alpha 0.0

screen countdown():
    default n = 3

    vbox:
        textbutton "3" action SetScreenVariable("n", 3)
        textbutton "2" action SetScreenVariable("n", 2)
        textbutton "1" action SetScreenVariable("n", 1)
        textbutton "0" action SetScreenVariable("n", 0)

    showif n == 3:
        text "Three" size 100 at cd_transform
    elif n == 2:
        text "Two" size 100 at cd_transform
    elif n == 1:
        text "One" size 100 at cd_transform
    else:
        text "Liftoff!" size 100 at cd_transform

label start:
    call screen countdown

スクリーン・ステートメント link

Ren'Py 言語にはスクリーンに作用する三つのスクリーンステートメントがあります。

これらのステートメントのうち二つはキーワード引数を取ります。これは python の引数と同様ですが、括弧の中にはキーワード引数のみが入ります。位置引数、可変長の位置引数 (*) とキーワード引数 (**) は許可されません。

Show Screen link

show screen ステートメントはスクリーンを表示します。スクリーン名と任意の引数リストを受け取ります。もしあるなら引数はそのスクリーンのスコープを初期化するために使用されます。

show screen ステートメントは任意で nopredict キーワードを受け取り、スクリーンの予測を禁止します。スクリーンの予測中にスクリーンへの引数は評価されます。スクリーン引数の評価が不測の副作用を起さないように確認してください。

警告

スクリーンの引数の評価が副作用を起すなら、あなたのゲームは予測しない方法で動作するかもしれません。

このように表示されたスクリーンは明示的に非表示にされるまで表示されます。これによりそれらで意図的に上書きが出来ます。

show screen overlay_screen
show screen clock_screen(hour=11, minute=30)

if rare_case:
    show rare_screen nopredict

Hide Screen link

hide screen ステートメントは現在表示されているスクリーンを非表示にします。そのスクリーンが表示されていなければ何もしません。

hide screen overlay_screen
hide screen clock

Call Screen link

call screen ステートメントはスクリーンを表示し、現在のインタラクションが終了するとそれを非表示にします。そのスクリーンが値を返すならその値は _return に代入されます。

これは imagemap を表示するために使用されます。 imagemap は Return() アクションを利用して値を変数 _return に代入するか、 Jump() アクションを使用してラベルにジャンプできます。

call screen ステートメントは任意で nopredict キーワードを受け取り、スクリーンの予測を禁止します。スクリーンの予測中にスクリーンへの引数は評価されます。スクリーン引数の評価が不測の副作用を起さないように確認してください。

警告

スクリーンの引数の評価が副作用を起すなら、あなたのゲームは予測しない方法で動作するかもしれません。

call screen my_imagemap

call screen my_screen(side_effect_function()) nopredict

スクリーンバージョン link

Ren'Py は Windows, Mac, Linux PC のような伝統的なマウスを持つデバイスと Android ベースのスマートフォンやタブレットのような最新のタッチベースのデバイス、両方で動作します。スクリーンバージョンはゲームが複数の種類のスクリーンを持てるようにし、実行中のハードウェアに最適なものを使用可能にします。

Ren'Py は config.variants にリストされた順番でバージョンを探索して使用するスクリーンバージョンを選択します。存在する最初のバージョンが使用されます。

環境変数 RENPY_VARIANT があれば空白でその変数を分割し、 None を追加して config.variants を初期化します。RENPY_VARIANT を 「medium tablet touch」や「small phone touch」のように設定すると PC で android デバイス用のスクリーンをテスト出来ます。

環境変数がなければバージョンのリストは以下のリストを順番に探索して現在のプラットフォームに対応するものを選びます。

"large"

比較的小さなテキストを快適に読め、ボタンを簡単にクリックできる十分大きな画面です。これはコンピューターの画面に使用されます。

"medium"

やや小さいテキストは読めるが、ボタンは快適に押せるためにはサイズを大きくしなければならない画面です。これはタブレットで使用されます。

"small"

テキストを読むためにも字を大きくする必要がある画面です。これは携帯やテレビで使用されます。 ( テレビは物理的には大きいですが、大概遠くて見にくいです。 )

"tablet"

画面の対角線が 6 インチタッチかそれ以上のタッチスクリーンベースのデバイスで定義されます。 ( 通常は「 medium 」が「 tablet 」の代わりに使用されます。 )

"phone"

画面の対角線が 6 インチタッチかそれ以下のタッチスクリーンベースのデバイスで定義されます。そのような小さなデバイスではボタンを十分に大きくして簡単に選択できるようにすることが重要です。 ( 通常は「 small 」が「 phone 」の代わりに使用されます。 )

"touch"

タッチスクリーンベースのデバイスで定義されます。

"tv"

TV ベースのデバイスで定義されます。

"ouya"

OUYA のコンソール上で定義されます。 ("tv""small" も定義されます。 )

"firetv"

Amazon Fire TV のコンソール上で定義されます。 ("tv" と "small" も定義されます。 )

"android"

すべての Android デバイスで定義されます。

"ios"

iPad ( "tablet""medium" も定義されます )や iPhone ("phone""small" も定義されます)のような iOS デバイスで定義されます。

"mobile"

Android や iOS のようなモバイルプラットフォームを定義します。

"pc"

Windows, Mac OS X, Linux で定義されます。 PCはマウスとキーボードを所持し、ボタンへのフォーカスと正確な移動が出来ると期待されます。

None

常に定義されます。

スクリーンバージョンを定義する例です。 :

# A variant hello_world screen, used on small touch-based
# devices.
screen hello_world():
     tag example
     zorder 1
     modal False
     variant "small"

     text "Hello, World." size 30