画像の表示

ビジュアルノベルを定義する特徴は、その名が表すとおり、ビジュアルです。Ren'Py には、画像を制御する 4 つのステートメントがあります。また、画像が表示される順番を定義するモデルをもっています。これにより、ビジュアルノベルに適した方法で画像を表示できます。

画像に使える 4 つのステートメントは:

• image - 新しい画像を定義します。

• show - レイヤーに画像を表示します。

• scene - レイヤーをクリアし、必要ならレイヤーに画像を表示します。

• hide - レイヤーからイメージを取り除きます。

画像を急に変えるとユーザーはびっくりするので、Ren'Py は with ステートメントを用意しています。これにより、場面の変わり目に効果が適用されます。

このページにリストされた(すべてではないですが)殆どのステートメントは Lint でチェックできますが、これは python での相当する物には当てはまりません。

概念

画像

画像は、show ステートメントを使って画面に表示されるものです。画像は名前と displayable でできています。画像がレイヤーに表示されるとき、その画像に対応する displayable がレイヤーに表示されます。

画像名 は、スペースで分けられた1つ以上の名前でできています。画像名を構成する最初の部分を 画像タグ と言います。名前のそれ以降の部分は、 画像属性 です。

例えば、 mary beach night happy という画像名があるとします。この画像タグは mary で、画像属性は beach, night, happy です。

displayable とは、スクリーンに表示できるものです。主に静止画像を表示するために使われます。これを指定するには、画像のファイル名を文字列として与えます。上述の例では、ファイル名として例えば mary_beach_night_happy.png を使います。しかし、画像は静止画像に限らず、 Ren'Py がサポートする displayable 全て を参照できます。ですから、画像を表示するのと同じステートメントが、アニメーション、全面色、その他の displayable にも使えます。

レイヤー

レイヤーとは、画面に表示された displayable のリストです。Ren'Py は複数のレイヤーをサポートしていて、ユーザー定義のレイヤーも使えます。レイヤーの順序はゲーム内で固定されています ( config.layers 変数で制御されます)。また、レイヤー内の displayable の順序は、scene ステートメントや show ステートメントが呼び出された順序と、そのステートメントに与えられたプロパティーとで制御されます。

Ren'Py 内部では、以下のレイヤーが定義されています:

master

これは、scene ステートメント、show ステートメント、hide ステートメントで使われるデフォルトのレイヤーです。主に、背景やキャラクタースプライトに使われます。

transient

ui 関数で使われるデフォルトのレイヤーです。このレイヤーは、インタラクションが終わる度に消去されます。

screens

このレイヤーは、スクリーン機能によって使われます。

overlay

ui 関数が overlay 関数の内部から呼び出されたときに使われるデフォルトのレイヤーです。このレイヤーは、インタラクションが再開する度に消去されます。

追加のレイヤーは renpy.add_layer() の呼び出しと様々なレイヤー関連の 設定変数 を使用して定義できます。 camera ステートメント の使用により、1つ以上の transforms をレイヤーに適用できます。

画像の定義

画像定義には 2 つの方法があります。画像ディレクトリーに画像ファイルを置くか、 image ステートメントで画像を定義するかです。前者は単純で、ディレクトリー内に適切な名前のファイルを配置するだけですが、後者は画像定義時に詳細な制御が出来、画像ファイル以外も画像として扱えます。

image ステートメントで定義された画像は画像ディレクトリーで定義されたものより優先されます。

画像 ディレクトリー

画像ディレクトリーは「 images 」と名付けられ、ゲームディレクトリーに配置されます。このディレクトリー以下に .jpeg や .jpg, jxl .png, webp 拡張子を持つファイルを配置すると、その拡張子が除外され、ファイル名の残りは強制的に小文字になります。その結果のファイル名が既に画像名に使用されていなければ画像名として使用されます。

この処理は画像ディレクトリー下のすべてのディレクトリーで起こります。例えば以下のすべてのファイルは画像 eileen happy を定義します。

game/images/eileen happy.png
game/images/Eileen Happy.jpg
game/images/eileen/eileen happy.png

画像ファイル名が指定されてその画像が見つからないと、 images ディレクトリーが検索されます。

オーバーサンプリング

デフォルトでは表示されたときのサイズは画像のピクセルでのサイズが定義します。例えば、ある画像が 1920x1080 ピクセルであり、ゲームが gui.init() を使用して、 1920x1080 で実行されるよう設定されていれば、その画像は画面全体を満たします。

オーバーサンプリングが有効なときは、その画像が表示されるサイズは画像サイズのものより小さくなります。例えば、ある画像が 3480x2160 であり、オーバーサンプリングが 2 ならば、各軸は半減し、画像は同じく 1920x1080 のウィンドウを満たします。

これは、画像がズームインされる可能性があり、さらなるディテールが必要な場合に便利です。オーバーサンプリングは config.physical_width や config.physical_height と組み合わせて、ゲームを高解像度グラフィックでリメイクする場合にも有効です。

画像の拡張子の前に '@' と数字が続くと、自動的にオーバーサンプリングが有効になります。例えば、eileen happy@2.png は2倍のオーバーサンプリングで、eileen happy@3x.png は3倍のオーバーサンプリングになります。オーバーサンプリングは Image() に oversample キーワード引数を与えても有効にできます。

あるディレクトリーに対して、その中の画像のオーバーサンプリング量も指定できます。例えば、 images/@2/eileen happy.png は 2 倍にオーバーサンプリングされます。

image ステートメント

image ステートメントを使用して画像を定義します。image ステートメントは、 image で始まり、画像名、等号 (=)、displayable を続けた1行の論理行で出来ています。例

image eileen happy = "eileen_happy.png"
image black = "#000"
image bg tiled = Tile("tile.jpg")

image eileen happy question = VBox(
    "question.png",
    "eileen_happy.png",
    )

画像が直接 game ディレクトリーにないとき、ディレクトリーを指定する必要があります。例えば、画像が game/eileen/happy.png なら、以下のように書けます。

image eileen happy = "eileen/happy.png"

image ステートメントは、ゲームメニューが表示される、または start ラベルが実行される前の初期化時に実行されます。 image ステートメントは init ブロックに含まれていないとき、優先度 500の init ブロックの中に含まれているかのように、初期化時に実行されます。

image ステートメントの ATL ブロック もご覧ください。

show ステートメント

show ステートメントを使用して画像をレイヤーに表示します。 show ステートメントは show で始まり、画像名、ゼロ個以上のプロパティーが続く1行の論理行でできています。

show ステートメントに与えられたものが既存の画像の正確な名前なら、その画像が表示されます。そうでなければ、Ren'Py は以下のような画像を一つ探します:

• show ステートメントで指定されたものと同じタグを持つ 画像

• show ステートメントで与えられた全ての属性を持つ画像

• 同じタグの画像がすでに表示されているなら、その画像と共通の属性を最も多く持つ画像

そのような画像が一つに決まらなければ、例外が発生します。

レイヤー上に同じタグの画像がすでに表示されているなら、それを新しい画像が置き換えます。そうでなければ、その画像がレイヤーの一番上に置かれます(つまり、ユーザーに最も近いところです)。 この順序は、zorder および behind プロパティーで変更できます。

show ステートメントは、インタラクションを起こしません。イメージを実際にユーザーに表示するためには、インタラクションを起こすステートメント(say, menu, pause, および with ステートメントなど) を実行しなければなりません。

show ステートメントは、以下のプロパティーを受け取ります:

as

as プロパティーは名前を受け取ります。画像が表示されるとき、画像タグの代わりにこの名前が使われます。これで、同じ画像をスクリーンの2箇所に表示できます。

at

at プロパティーはコンマで区切られた一つ以上の単純式を受け取ります。それぞれの式の評価結果は transform でなければなりません。この画像に、その transform が左から順に適用されます。

at 節が与えられていなければ、Ren'Py は画像に適用されている ATL または Transform で作成された transform を全て保持します。 transform が存在しなければ、画像は default transform を使って表示されます。

あるタグと関連付けられた transform を置き換えてその transform プロパティーを変更する方法は transformの置き換え の項目を参照してください。

behind

カンマで区切られた一つ以上の名前を受け取ります。それぞれの名前は画像タグとして受け取られます。画像は、現在表示されている画像の中で、与えられたタグを持つもの全ての後に表示されます。

onlayer

名前を受け取ります。指名されたレイヤーに画像を表示します。

zorder

整数を受け取ります。これは画像のレイヤー上における相対的な順序を指定します。この数字が大きいほどユーザーに近くなります。これは通常 Ren'Py ゲームのコードでは使いませんが、他のエンジンからコードを移植するときに便利です。また、後に表示される他のより小さな zorder の画像より上に表示されるように画像を表示するのにも、他のレイヤーに表示する手間がないので便利です。

以下の画像を定義したとします:

image mary night happy = "mary_night_happy.png"
image mary night sad = "mary_night_sad.png"
image moon = "moon.png"

show ステートメントの例です。

# Basic show.
show mary night sad

# Since 'mary night sad' is showing, the following statement is
# equivalent to:
# show mary night happy
show mary happy

# Show an image on the right side of the screen.
show mary night happy at right

# Show the same image twice.
show mary night sad as mary2 at left

# Show an image behind another.
show moon behind mary, mary2

# Show an image on a user-defined layer.
show moon onlayer user_layer

属性管理

上述のようにして属性は設定、追加、置き換えできます。

マイナス記号を使用しても除去できます。

# show susan being neutral
show susan

# show susan being happy
show susan happy

# show susan being neutral again
show susan -happy

Show expression

show ステートメントの変種として、画像名の代わりに予約語 expression を使い、その後に単純式を続けるものがあります。この式の評価は、displayable でなければなりません。その displayable がレイヤーに表示されます。この displayable を hide するためには、このステートメントでタグを与えておかなければなりません。

例

show expression "moon.png" as moon

Show Layer

show layer ステートメントについては後述の camera ステートメント と共に記述されています。

scene ステートメント

scene ステートメントはレイヤーから全ての displayable を削除し、その後、そのレイヤーに画像を表示します。このステートメントは、予約語 scene 、画像名、ゼロ個以上のプロパティーの順でできています。画像は、show ステートメントと同じように表示されます。また、scene ステートメントは show ステートメントと同じプロパティーを受け取ります。

scene ステートメントは、主に背景レイヤーに画像を表示するのに使います。例 :

scene bg beach

scene expression show ステートメントと同様、scene ステートメントも画像名の代わりに式を受け取れます。

レイヤーの消去 画像名が全く与えられないとき、scene ステートメントはレイヤーから全ての displayable を消去し、代わりの画像は表示しません。

hide ステートメント

hide ステートメントは、レイヤーから画像を取り除きます。このステートメントは、予約語 hide、画像名、ゼロ個以上のプロパティーの順でできています。hide ステートメントは画像名から画像タグを受け取り、そのタグを持つ画像がレイヤーにあれば、その画像を非表示します。

hide ステートメントが必要になることはあまりありません。あるスプライトがあるキャラクターを表しているなら、hide ステートメントが必要なのはそのキャラクターがシーンから退場する時だけです。キャラクターが表情を変えるときは、show ステートメントを使うのが望ましいです。show ステートメントは、同じタグの画像を自動的に置き換えてくれます。

hide ステートメントは、以下のプロパティーを受け取ります:

onlayer

名前を受け取ります。指名されたレイヤーから画像を隠します。

例

e "I'm out of here."

hide eileen

こうは書かずに:

hide eileen
show eileen happy

こう書いてください:

show eileen happy

with ステートメント

with ステートメントを使用して画面が変わるときにトランジション効果を適用し、画像の表示や非表示を緩やかにします。with ステートメントは予約語 with と、それに続く評価がトランジションか特殊値 None である単純式でできています。

トランジション効果は、前のインタラクション (会話、選択肢、トランジション) が終わった時点の画面の内容と、scene、show、hide ステートメントが実行された後の内容の間で適用されます。

with ステートメントは、インタラクションを起こします。インタラクションの時間幅はユーザーが制御できますし、ユーザーが早く終わらせることもできます。

利用できるトランジションの一覧は、 トランジション の章をご覧ください。

with ステートメントの例です。

show bg washington
with dissolve

show eileen happy at left
show lucy mad at right
with dissolve

これは、2 つのトランジションを行います。最初の with ステートメントは、 dissolve トランジションを使い、スクリーンを washington 背景に変えます(dissolve トランジションはデフォルトで、0.5 秒のディゾルブと定義されています)。

第二のトランジションは、Eileen と Lucy の画像が表示された後におこります。これにより背景のみの場面から、3 つ全ての画像がある場面にディゾルブします。結果として 2 つの新しい画像がディゾルブして現れます。

with None

上述の例には 2 つのディゾルブがあります。しかし背景は即座に現れその後に 2 人のキャラが現れるようにするにはどうするのでしょうか？最初の with ステートメントを単純になくしてしまうと、3 つの画像すべてがディゾルブして現れてしまいます。背景が即座に現れるようにしたいです。

with ステートメントは、特殊な値 None を与えると、動作が変わります。 with None ステートメントは、ユーザーに表示するものを変えない、省略されたインタラクションを起こします。次のトランジションは、この省略されたインタラクションが終わった時点で表示されている場面から始まります。

例

show bg washington
with None

show eileen happy at left
show lucy mad at right
with dissolve

washington 背景から、3 つの画像が表示されている場面に、一度だけトランジションが起こります。

scene、show、hide ステートメントの with 節

show、scene、hide ステートメントは、任意で with 節を受け取れます。これは、画像の表示や非表示にトランジションを組み合せます。この節はステートメントと同じ論理行の末尾につづきます。 予約後 with に始まり、単純式が続きます。

with 節をつけるのは、 with None ステートメントを前に、with ステートメント を後に置くことに相当します。

show eileen happy at left with dissolve
show lucy mad at right with dissolve

これは次と等しいです:

with None
show eileen happy at left
with dissolve

with None
show lucy mad at right
with dissolve

これは Show Screen と Hide Screen ステートメントにも当てはまりますが、 Call Screen では少し違う動作をすることに注意してください。

Camera と show ステートメント

camera ステートメントは transform や ATL transform を次のような構文によってレイヤー全体 (例えば master) に適用できます:

camera at flip

または:

camera:
    xalign 0.5 yalign 0.5 rotate 180

transform の適用をやめるには、次のようにします:

camera

camera ステートメントは camera と at または : の間に任意のレイヤー名を受け取ります。

camera mylayer at flip

show layer ステートメントは camera の旧バージョンですが、いくつかの差異があるためまだ有用です。

show layer master:
    blur 10

違いは次の通りです :

• show layer で適用された transform は次の scene ステートメントでクリアされる一方、 camera transforms は明白にクリアされるまで残ります。

• show layer はレイヤー名を要求しますが、 camera はデフォルトで master レイヤーを対象にします。

ウィンドウの表示・非表示

window ステートメントを使用してキャラクターが話していないときにもウィンドウを表示するかを制御します ( 例 トランジション、ポーズ中 )。 window show ステートメントはウィンドウを表示させ、window hide ステートメントはウィンドウを非表示にします。

任意のトランジションが指定されると、ウィンドウの表示、非表示時に使用されます。指定されないと、デフォルトでは config.window_show_transition と config.window_hide_transition になります。 トランジションとして None を指定するとその実行を防ぎます。

ウィンドウ自身は config.empty_window を呼び出して表示されます。デフォルトではナレーターに空の文字列を話させます。

show bg washington
show eileen happy
with dissolve

window show dissolve

"I can say stuff..."

show eileen happy at right
with move

"... and move, while keeping the window shown."

window hide dissolve

画像関数

renpy.add_layer(layer, above=None, below=None, menu_clear=True, sticky=None)

新しいレイヤーを追加します。レイヤーが既に存在すればこの関数はなにもしません。

below または above のどちらかが指定さなければいけません。

layer

追加する新しいレイヤー名の文字列です。

above

None または新しいレイヤーの下に配置されるレイヤー名の文字列です。

below

None または新しいレイヤーの上に配置されるレイヤー名の文字列です。

menu_clear

True ならこのレイヤーはゲームメニューコンテキストに入るとクリアされ、出るときに復元されます。

sticky

True ならこのレイヤーに追加されたタグは非表示になるまでこのレイヤーをそのデフォルトレイヤーにします。 None なら他の sticky レイヤーが既に存在しているときのみこのレイヤーは sticky レイヤーになります。

renpy.can_show(name, layer=None, tag=None)

name で画像を表示出来るか決定します。これは name をタグと属性として解釈します。これは layer 上の現在表示されている tag の画像の属性と組み合わされ、表示する画像を 1 つに決定しようとします。1つの画像が表示可能なら、その画像名をタプルで返し、そうでなければ None を返します。

tag

画像属性を所得する画像タグです。未指定なら name の最初の要素が使用されます。

layer

チェックするレイヤーです。 None なら tag のデフォルトレイヤーを使用します。

renpy.change_zorder(layer, tag, zorder)

layer 上の tag の zorder を zorder に変更します。

renpy.check_image_attributes(tag, attributes)

指定したタグと属性を持つ唯一の画像があるかチェックします。あれば、その属性を順番に返します。そうでなければ None を返します。

renpy.clear_attributes(tag, layer=None)

tag 画像のすべての画像属性をクリアします。そのタグに画像属性が泣ければ、おれは何もしません。

layer

チェックするレイヤーです。 None なら tag のデフォルトレイヤーを使用します。

renpy.copy_images(old, new)

ある接頭辞で始まる画像を他の接頭辞で始まるものにコピーします。例 :

renpy.copy_images("eileen", "eileen2")

「 eileen 」で始まるすべての画像に対して「 eileen2 」で始まる画像を作成します。例えば「 eileen happy 」が存在するなら、「 eileen2 happy 」が作成されます。

old

スペース区切りのコピー対象画像名の要素の文字列です。

new

スペース区切りの新しい画像名の要素の文字列です。

renpy.flush_cache_file(fn)

fn ファイルを参照するすべての画像イメージのキャッシュをクリアします。ディスクの画像ファイルが変わったときにはこれを呼び出して、 Ren'Pyに新バージョンの使用を強制します。

renpy.get_attributes(tag, layer=None, if_hidden=None)

tag の画像属性のタプルを返します。画像タグが最後に非表示されてから画像属性がないときは、if_hidden を返します。

layer

チェックするレイヤーです。 None なら tag のデフォルトレイヤーを使用します。

renpy.get_available_image_tags()

定義されている画像タグのリストが返されます。

renpy.get_hidden_tags(layer='master')

現在 layer 上で非表示されているが、まだ画像属性を持つ画像タグのセットが返されます。

renpy.get_image_bounds(tag, width=None, height=None, layer=None)

tag を持つ画像が layer に存在すれば、その画像の矩形領域を返します。画像が見つからなければ None を返します。

矩形領域は (x, y, width, height) のタプルです。タプルの要素はピクセル数で表され、小数にも出来ます。

width, height

画像を格納する領域の幅と高さです。 None ならデフォルトでそれぞれスクリーンの幅と高さになります。

layer

None なら tag のデフォルトレイヤーを使用します。

renpy.get_ordered_image_attributes(tag, attributes=(), sort=None)

ユーザーに提供される順にの画像属性のリストを返します。

attributes

存在すれば、指定された属性と互換性のある属性のみが考慮されます(互換性とはその属性が同時に一つの画像にあることです)。

sort

None でなければ、これで返される属性のリストがソートされます。これは tiebreaker として使用されるべき引数1つの関数です。詳細は`このチュートリアル <https://docs.python.org/3/howto/sorting.html#key-functions>`_ を参照してください。

renpy.get_placement(d)

これは displayable d の位置を所得します。displayable はレンダリングされると位置が変わる可能性があり、最初にレンダリングされるまでは存在しない可能性もあるのでこの情報にはあまり信頼がありません。

これは以下の属性を持つオブジェクトを返し、それぞれがスタイルプロパティーに対応しています。

• pos

• xpos

• ypos

• anchor

• xanchor

• yanchor

• offset

• xoffset

• yoffset

• subpixel

renpy.get_registered_image(name)

同じ名前の画像が 登録されて いればそれを、そうでなければ None を返します。

renpy.get_say_image_tag()

現在話しているキャラクターに関連する (そのキャラクターの image 引数に指定された) タグ を返します。話しているキャラクターがいない、または現在のキャラクターが画像タグと関連付けられていなければ None を返します。

renpy.get_showing_tags(layer='master', sort=False)

現在 layer 上に表示されている画像タグのセットが返されます。sort が True なら、後ろから前の順でタグのリストが返されます。

renpy.get_zorder_list(layer)

layer に対する (tag, zorder) のペアのリストを返します。

renpy.has_image(name, exact=False)

name 画像が存在すれば Ture を、そのような画像がなければ False を返します。

name

画像名の文字列か、画像名を要素とする文字列のタプルです。

exact

その正確な名前で画像が存在する場合のみ True を返します。正規表現はマッチしません。

renpy.list_images()

Ren'Py に追加された画像を、名前と要素間にスペースを置いた文字列のリストとして返します。

renpy.mark_image_seen(name)

その名前の画像を現在のユーザーがすでに閲覧しているものとしてマークします。

renpy.mark_image_unseen(name)

その名前の画像を現在のユーザーではまだ閲覧していないものとしてマークします。

renpy.seen_image(name)

その名前の画像がユーザーに一度でも閲覧されていれば True を返します。画像は show 、 scene ステートメントか renpy.show() 関数を使用して表示されると閲覧されたことになります ( 表示直後に hide されるなど、実際にはユーザーが画像を見ていない場合もあることに注意してください )。

renpy.showing(name, layer=None)

name と同じタグを持つ画像が layer 上に表示されていると True を返します。

image

画像名の文字列や、画像名の各要素のタプルです。画像タグだけの文字列でもかまいません。

layer

チェックするレイヤーです。 None なら tag のデフォルトレイヤーを使用します。

renpy.start_predict(*args)

この関数は 1 つ以上の displayable を引数として受け取ります。 renpy.stop_predict() によって除外されるまで、 それらの displayable をインタラクション毎に予測させます。

displayable 名が1つ以上の * を含む文字列であるなら、アスタリスクがワイルドカードパターンとして使用できます。文字列に少なくとも1つ . があれが、そのパターンはファイルネームに、そうでなければ画像名にマッチします。

例

$ renpy.start_predict("eileen *")

eileen の名前を持つすべての画像を予測します。

$ renpy.start_predict("images/concert*.*")

image ディレクトリ内の concert で始まるすべての画像にマッチします。

予測はゲームプレイ中ずっと発生します。予測の完了を待つには renpy.pause() に predict 引数を使用します。

renpy.stop_predict(*args)

この関数は 1 つ以上の displayable を引数として受け取ります。それらの displayable のインタラクション毎の予測を停止させます。

ワイルドカードパターンは renpy.start_predict() で述べられるように使用可能です。

以下も参照してください

ステートメントに相当するもの : ここで述べた機能のほとんどを Python のコンテキストで使用する方法です。

Displayable : 基本的な画像の他、より多様な表示するできるオブジェクトがあります。