98
回編集
差分
ナビゲーションに移動
検索に移動
スクリプトの日本語化(kagi)
{{Version|timeless}}
※2025/10/6、英wikiよりkagi翻訳を通しました。機械翻訳なので一部不自然な日本語があるかもしれません。ぜひ編集してくれるとありがたいです。
※一部表示が破壊されているところがあります。
'''スクリプト'''は、開発者が許可した範囲で、独自のスクリプト言語を使ってゲームのコンテンツを追加・変更できる仕組みです。
読みやすく、add_gold や set_variable のような名前を用います。
'''スクリプトは common/ と events/ フォルダで使用されます。'''
これは決断、インタラクション、アクティビティ、さらに宗教・文化・伝承などの定義にも拡張されます。
スクリプトではないもの:
* AI や軍の挙動の大部分はゲームコードで処理されており、モッダーからはアクセスできません。このような機能を「ハードコードされている」と呼びます。
* [[Interface|UI]] は別システムであり、いくつかの例外を除き、UI でスクリプトを使ったり、スクリプト内で UI の関数を使ったりはできません。UI でスクリプトを実行するには [[Interface#Scripted GUIs|Scripted GUIs]] を使ってください。
* [[History modding]] も少し異なる静的な仕組みを使いますが、スクリプトのエフェクトを利用できます。
== 基本 ==
ここではスクリプト言語全体のクイックガイドを示します。
==== ドキュメント ====
ゲーム内コンソールの <code>script_docs</code> コマンドを使うと、利用可能な関数一覧のログを生成できます。
ログは <code>Documents\Paradox Interactive\Crusader Kings III\logs</code> に作成されます。
特に、effects、triggers、event_targets のログを確認してください。
そこには次の3つの一般的な関数の種類が列挙されています:
* '''effects''' - <code>add_gold</code> のように何かを実行します。<code>immediate = {}、effect = {}、on_accept = {}</code> のようなエフェクトブロックで使用します。
* '''triggers''' - <code>is_ai = yes</code> のように条件を判定して真偽値を返します。値を返すものもあります。<code>limit = {}、trigger = {}</code> などのトリガーブロックで使用します。
* '''event targets''' - 別のゲームオブジェクトを選択します。例えば <code>primary_heir</code> は後継者を選びます。これらのオブジェクトを「スコープ」と呼び、それらの切り替えを「スコーピング」と呼びます。
logs フォルダにはエラーやデバッグのログもあり、エラーの発見やスクリプトのテストに役立ちます。
フォルダ内には .info ファイルもあり、各ファイルの文法が記載されています。
==== 制限事項 ====
* オペレーティングシステムへのアクセスは不可
* 1次元配列
* 文字列操作は不可
* インライン計算は不可
* 実際のゲームコードより遅い
下記の [[Scripting#Workarounds|回避策]] にいくつかの解決方法があります。
==== スクリプト言語の名称 ====
このスクリプトで使われている言語に公式名称はなく、単に「Paradox スクリプト言語」と呼ばれます。
ただし、[[forum:1170261|Jomini]] ツール群のライブラリが作られた際の更新にちなんで、開発者の一部は「Jomini スクリプト」と呼び始めています。
「Clausewitz」はゲームエンジンの名称です。
==== テスト ====
スクリプトを手早くテストする方法がいくつかあります:
* コンソールで effect または trigger という語を前につければ、短いスクリプトを実行できます。例:
<code>effect add_gold = 100</code> や <code>trigger is_ai = yes</code>
* エクスプローラーのスクリプトランナーを使う（コンソールコマンド <code>explorer</code>）
* run/ フォルダに .txt ファイルでスクリプトを置き、コンソールコマンド <code>run filename.txt</code> で実行
* <code>-develop</code> 起動オプションでゲームを実行し、イベントや決断を即時リロード
エラーログを開いたままにして問題を確認しましょう。コンソールコマンド <code>release_mode</code> でゲーム内にエラートラッカーを表示します。
<code>-debug_mode</code> 起動オプションでゲームを立ち上げ、コンソールを使用します。
スクリプトの検証には有志の [https://github.com/amtep/ck3-tiger CK3 Tiger]（VS Code 向け拡張あり）を利用できます。
== 基本 ==
=== 構文 ===
多くのスクリプトは次の構造に従います:
<code>x = y</code>
<code>x = { y = z }</code><syntaxhighlight lang="c">
x = {
a = b
e = {
f = g
}
}
</syntaxhighlight>例:
* <code>is_alive = yes</code>
* <code>add_gold = 100</code>
* <code>debug_log = "hello world"</code>
* <code>player_heir = { marry = root }</code>
エフェクトやトリガーは単体では使わず、必ず別のパラメータを伴います。単に <code>= yes</code> の場合もあります。
トリガーは <code>= no</code> で否定をチェックすることもできます。
<code>is_ai = no</code> は <code>NOT = { is_ai = yes }</code> と同じです。
値を判定するトリガーは、その値を返すこともあります。
<code>add_gold = age</code> は、キャラクターの年齢に等しい金額を加算します。
<code>target</code> を持つ複雑なトリガーには、丸括弧でターゲットを指定する特別な構文があります:
<code>add_gold = "opinion(liege)"</code>
ここでは引用符が必要です。
=== スコープ ===
スコープとは、キャラクターや伯爵領などのゲーム内の实体です。
エフェクトやトリガーは、適切なスコープで使用する必要があります
* 例: <code>age</code> トリガーはキャラクターに対してのみ機能します。
イベントターゲットによって、あるスコープから別のスコープへ切り替えられます。これをスコーピングと呼びます。
* <code>primary_heir</code> はイベントターゲットで、キャラクターでのみ使用でき、主要後継者を返します。
対応スコープはログで確認してください。
なお、イベントターゲットはどこでも使え、イベント専用ではありません。
=== 連鎖（チェイニング） ===
スコープは <code>x.y.z</code> のように連鎖できます。
<code>primary_heir.faith.religious_head</code> は次と同じです:<syntaxhighlight lang="c">
primary_heir = {
faith = {
religious_head = { }
}
}
</syntaxhighlight>
=== 接頭辞 ===
文化・信仰・宗教・称号・キャラクターを直接参照するには、<code>culture:</code> のような特別な接頭辞が必要です。例:
<code>set_culture = culture:english</code>
<code>set_character_faith = faith:orthodox</code>
<code>capital_county = title:c_byzantion</code>
<code>marry = character:123456</code>
<code>english</code> のようなキーはファイルで、キャラクター ID はデバッグツールチップで探してください。
=== 整形 ===
波括弧内のスクリプトは「コードブロック」と呼ばれます。
インデント（行頭のタブ）は実行には影響しません。理論上は、ほとんどのスクリプトを1行にまとめても動作します。
しかし可読性のため、各コードブロックは1段階ずつインデントしましょう。これにより、どこで開閉しているかが見やすくなり、エディタでブロックを折りたためます。
コメントは # を先頭につけます。
'''例外'''
on_actions の events のように、対になるパラメータなしで複数の要素を受け付けるブロックがあります。例:<syntaxhighlight lang="c">
on_death = {
events = {
death_management.0096
death_management.0097
death_management.0098
}
}
</syntaxhighlight>
== キーワード ==
<code>root</code> - スクリプトの根本にある、スクリプトが実行されている対象。
イベントでは、<code>root</code> はそのイベントを受け取ったキャラクターです。
そのイベント内では、どこでも <code>root</code> が同じキャラクターを参照します。
例: <code>primary_heir = { set_relation_grudge = root }</code>
<code>prev</code> - スクリプト内の直前のスコープ<syntaxhighlight lang="c">
primary_heir = {
primary_spouse = {
set_relation_soulmate = prev
}
}
</syntaxhighlight>ここでは、後継者の配偶者がその後継者のソウルメイトになります。
<code>prevprev</code> は存在せず、1つ前にしか戻れない点に注意してください。
<code>prev = { prev = {</code> のように2回使うと、元のスコープに戻ります。
<code>this</code> - 現在のスコープを参照します。
多くの場合不要ですが、次のようなケースでは便利です:<syntaxhighlight lang="c">
county.holder = {
OR = {
this = root
this = root.primary_spouse
}
}
</syntaxhighlight>
== 演算子 ==
==== 論理演算子 ====
スクリプトには以下があります:
AND, OR, NOT, NOR, NAND
使用例:<syntaxhighlight lang="c">
OR = {
is_ai = yes
gold > 100
}
</syntaxhighlight>これは、そのキャラクターが AI である、または所持金が 100 を超える場合に真になります。
ブロック内には複数のパラメータを置け、<code>OR = { AND = { NOT = {...</code> のように入れ子にもできます。
'''AND''' は全ての条件が真なら真。
'''OR''' はいずれかの条件が真なら真。
'''NOT''' と '''NOR''' は実際には同じで、全ての条件が偽なら真。
'''NAND''' はいずれかの条件が偽なら真。
<code>limit = {}</code> のようなトリガーブロックは、デフォルトで AND として動作し、複数のパラメータを受け付けます。
可読性のため、演算子は大文字で書くのが一般的です（必須ではありません）。
==== 関係演算子 ====
スコープの比較には <code>=</code> を使います。例: <code>primary_heir = primary_spouse</code>。
<code>!=</code> は不等（<code>NOT = { x = y }</code> と同じ）。
値の比較には <code>< <= = != > >=</code> を使います。
<code>?=</code> は特殊な演算子で、そのオブジェクトが存在するかを確認してから比較やスクリプト実行を行います。
<code>capital_county ?= title:c_byzantion</code> は、まずそのキャラクターに首都伯爵領があるかを確認します。次と同じです:<syntaxhighlight lang="c">
exists = capital_county
capital_county = title:c_byzantion
</syntaxhighlight>これにより未設定スコープによるエラーを避け、スクリプトを簡潔にできます。
== 保存スコープ ==
保存スコープは変数に似ています。
あるオブジェクトを保存して後で参照でき、そのスクリプトの実行中のみ存在します。
<code>save_scope_as = name</code>
<code>scope:name = { # 何かを行う }</code><syntaxhighlight lang="c">
primary_heir = { save_scope_as = my_son }
scope:my_son = { death = natural }
</syntaxhighlight>保存スコープは、同じスクリプトから呼ばれる他のイベントやスクリプト化エフェクトにも引き継がれますが、スクリプト全体の実行が終わると消えます。
<code>save_scope_value_as</code> は値や文字列フラグを保存でき、同じ方法で参照します。<syntaxhighlight lang="c">
save_scope_value_as = {
name = cost
value = primary_heir.age
}
add_gold = scope:cost
</syntaxhighlight><syntaxhighlight lang="c">
save_scope_value_as = {
name = kill_locale
value = flag:tower
}
if = {
limit = { scope:kill_locale = flag:tower }
# 何かを行う
}
</syntaxhighlight>
トリガー内では <code>save_temporary_scope_as</code> と <code>save_temporary_scope_value_as</code> を使ってください。
通常版はそこで動作しません。
一部の保存スコープは、on_actions やキャラクターインタラクション内でゲーム側があらかじめ用意しています。
例えばインタラクションでは、<code>scope:actor</code> はインタラクションを開始したキャラクター、<code>scope:recipient</code> は対象キャラクターです。
on_actions については、そのファイル内のコメントに利用可能な保存スコープが記載されています。
重要: イベントターゲットや <code>root</code>、<code>prev</code> のようなキーワードの前に <code>scope:</code> を付けないでください。
<code>scope:</code> は、あなたやゲームが以前に保存した保存スコープにのみ使用します！
== 変数 ==
変数は値を保持するコンテナです。
変数には、数値・キャラクター・ブール値・文字列フラグなど、ほぼ何でも保持できます。
データ型の宣言は不要です。数値変数は固定小数点です。例:<syntaxhighlight lang="c">
set_variable = {
name = test
value = 10
}
</syntaxhighlight><code>var:</code> で値を取得します。
<code>add_gold = var:test</code>
<code>marry = var:my_crush</code>
<code>set_variable = test</code> のように、変数は簡単に設定できます。これは <code>value = yes</code> で変数を設定するのと同じです。
変更には <code>change_variable</code>、削除には <code>remove_variable</code> を使います。例:
<code>change_variable = { name = test add = 1 }</code> と <code>remove_variable = test</code>
ここでは var: を使わず、変数名だけを記述する点に注意してください！
value フィールドは拡張でき、複数の change_variable を使わずに計算できます:<syntaxhighlight lang="c">
set_variable = {
name = test
value = {
add = 10
divide = 5
subtract = 1
}
}
</syntaxhighlight>
格納方法に応じて、変数にはいくつかの種類があります:
* '''通常'''（<code>set_variable</code>）- エフェクトを使用した[[Scopes|スコープ]]に保存されます。アクセスするには、まずそのオブジェクトにスコープを移す必要があります。
** <code>var:</code> で参照します。<code>primary_heir.var:my_sons_birthday</code> のようにチェインも可能。
** キャラクターに保存した場合、そのキャラクターが死亡すると失われます！その場合は死者変数を使用してください。
* '''グローバル'''（<code>set_global_variable</code>）- グローバルに保存され、どこからでも参照できます。もちろん、同名のグローバル変数は一つだけ存在できます。
** <code>global_var:</code> で参照します。
* '''ローカル'''（<code>set_local_variable</code>）- スクリプト実行中のみ存在する一時変数で、どのオブジェクトにも保存されません。
** <code>local_var:</code> で参照します。カウンターとして有用な場合がありますが、使用頻度は低めです。
* '''死者'''（<code>set_dead_character_variable</code>）- 死亡キャラクターに保存され、一定期間後に削除されます。これはパフォーマンス上の理由です。
** <code>dead_var:</code> で参照します。<code>change_</code> エフェクトはありません。
グローバルとローカルには、変更・削除用の固有エフェクトがあります:
<code>change_global_variable</code>、<code>remove_global_variable</code> および <code>change_local_variable</code>、<code>remove_local_variable</code>
UI とローカライズでは、変数は次のように表示できます:
<code>"[GetPlayer.MakeScope.Var('test').GetValue]"</code> - プレイヤーに設定された通常変数の値（数値）を返します。
変数が別のキャラクターを保持している場合は GetValue の代わりに GetCharacter を使います。他の型も同様です。
グローバル変数は次のように表示します:
<code>"[GetGlobalVariable('test').GetValue]"</code>
詳しくは [[Variables]] および [[Interface#Displaying a variable or script value|UI に変数やスクリプト値を表示する]] を参照してください。
== ステートメント ==
==== if / else / else_if ====
limit = {} が true を返したときに効果を実行します。<syntaxhighlight lang="c">
if = {
limit = { is_ai = no }
add_gold = 100
}
</syntaxhighlight>これは、そのキャラクターがAIでない場合にのみゴールドを追加します。
limit が false のときは、<code>if</code> ブロックの直後に <code>else</code> を使って別の効果を実行できます。その効果に別の条件を追加するには <code>else_if</code> を使います。<syntaxhighlight lang="c">
if = {
limit = {
# condition
}
# effect
}
# optional
else_if = {
limit = { #condition }
# effect
}
else = {
# effect
}
</syntaxhighlight>複数の <code>else_if</code> を続けて使用できます。
注意点:
<code>limit</code> は AND ブロックのように動作するため、AND を使わなくても複数の条件を入れられます。
効果は必ず <code>if</code> の中、<code>limit</code> の外に置いてください。ここは間違えやすいポイントです。
==== switch ====
同じトリガーに対して多数の else_if をチェックしている場合は、switch に置き換えられます。
switch は、トリガーの値に一致する効果を1つ選びます。<syntaxhighlight lang="c">
switch = {
trigger = #some trigger
#value = { #effect }
#value = { #effect }
...
}
</syntaxhighlight>例:<syntaxhighlight lang="c">
switch = {
trigger = has_culture
culture:english = { add_gold = 10 }
culture:french = { add_gold = 20 }
culture:italian = { add_gold = 30 }
}
</syntaxhighlight>これは次と同一です:<syntaxhighlight lang="c">
if = {
limit = { has_culture = culture:english }
add_gold = 10
}
else_if = {
limit = { has_culture = culture:french }
add_gold = 20
}
else_if = {
limit = { has_culture = culture:italian}
add_gold = 30
}
</syntaxhighlight>
==== while ループ ====
<code>while</code> はアクションを複数回繰り返すために使います。
<code>count</code> を使えば所定回数、<code>limit</code> を使えば条件が false になるまで実行を続けられます。
例:<syntaxhighlight lang="c">
while = {
count = 10
add_gold = 100
}
while = {
limit = { gold > 0 }
remove_short_term_gold = 50
}
</syntaxhighlight><code>while</code> はデフォルトで1000回に制限されており、誤って無限ループになるのを防ぎます。
ループを途中で抜ける方法はありません。
==== trigger_if / trigger_else / trigger_else_if ====
<code>trigger_if</code> は <code>limit</code> ブロックが true の場合にのみトリガーをチェックします。false の場合、そのチェックはスキップされます。
例: キャラクターがAIでない場合に、独立した支配者かどうかをチェックします。
trigger_if = {
limit = { is_ai = no }
is_independent_ruler = yes
}
<code>trigger_else_if</code> は、if/else と同様に <code>trigger_if</code> の後に使用できます。<syntaxhighlight lang="c">
trigger_if = {
limit = { ... }
...
}
trigger_else_if = {
limit = { ... }
...
}
trigger_else = {}
</syntaxhighlight>スクリプトによっては、最後に trigger_else が必要な場合があります。うまく動かないときは追加してみてください。
<code>trigger_if</code> はトリガーブロック内でのみ使用し、効果内では使わないようにしてください。
== リスト / 配列 ==
リストは、変数と同様に、複数のオブジェクト、変数、文字列フラグを保持できます。
リストは他のリストを保持できません。
リストには一時的なものと永続的なものの2種類があります。
UI は変数リストやグローバル変数リストのような永続リストを表示できます。参照: [[Interface#Displaying data lists|Interface/Displaying_data_lists]]
ややこしいことに、ローカル変数リストは永続ではありません。
リストを作るには、以下のコマンドのいずれかで各アイテムを追加します:
'''一時:'''
* <code>add_to_list</code> - 単純なリストに追加します。スクリプト実行中にのみ存在します
* <code>add_to_local_variable_list</code> - 似ていますが、一定期間後にリストから削除される「期間」をアイテムに付与できます
* <code>add_to_temporary_list</code> - 他と異なり、トリガーブロック内でも使用できます
'''永続:'''
* <code>add_to_variable_list</code> - 効果が実行されたスコープに保存されるリストへ追加します。期間をサポート
* <code>add_to_global_variable_list</code> - グローバルな永続リストへ追加します。期間をサポート
リストがまだ存在しない場合、これらのコマンドのいずれかがリストを作成し、アイテムを追加します。
すでにアイテムがリストにある場合、重複はしません。
正しい文法は effects.log を参照してください。
<code>add_to_variable_list</code> は紛らわしい文法である点に注意してください。
そのリストを保持するスコープで効果を実行し、ターゲット側では実行しないようにしてください。
イテレーターではよく次のように使います。まず root にスコープしてリストをそこに保存し、次に直前のスコープをターゲットとして追加します。<syntaxhighlight lang="c">
every_ruler = {
root = {
add_to_variable_list = {
name = rulers
target = prev
}
}
}
</syntaxhighlight>
リストにアイテムが入っているかをチェックするには:
<code>is_in_list, is_target_in_variable_list, is_target_in_global_variable_list, is_target_in_local_variable_list</code>
アイテムを削除するには:
<code>remove_from_list, remove_list_variable, remove_list_local_variable, remove_list_global_variable</code>
単純なリストを一括クリアする効果はありません。クリアできるのは変数リストのみです:
<code>clear_variable_list, clear_global_variable_list, clear_local_variable_list</code>
単純なリストをクリアするには、リストを走査して各アイテムを削除してみてください。
ほとんどの場合、リストを作る前に <code>clear_variable_list</code> を実行し、再作成時に古いアイテムが残らないようにします。
存在しないリストをクリアしようとしてもエラーにはなりません。
<code>*_list_size</code> トリガーはサイズをチェックできますが、その値を返すことはできません。
サイズを値として使う必要がある場合は、リストを走査してアイテム数を数えてください。スクリプト値が役に立ちます。common/script_values の .info ファイルを参照してください。
== イテレーター ==
イテレーターは一連のアイテムを走査し、各アイテムに対して効果やトリガーを実行します。
例:<syntaxhighlight lang="c">
every_ruler = {
limit = { age > 20 }
add_gold = 100
}
</syntaxhighlight>これは20歳より上のすべての支配者に100ゴールドを追加します。
<code>limit = {}</code> は任意です。false を返した場合、その効果は実行されません。
<code>every_living_character = { every_province = {</code> のようなことはしないでください。9000の州を、存命キャラクター2万人分だけ繰り返すことになり、ラグの原因になります。
===== 効果イテレーター =====
これらはアイテムに対して何らかの効果を実行し、''効果'' ブロック内でのみ使用できます:
* <code>every_x</code> - 追加された順に全アイテムを走査
* <code>ordered_x</code> - <code>age</code> のような値で並べ替え。全件走査または1件選択が可能
* <code>random_x</code> - ランダムに1件選択。確率は調整可能
===== トリガーイテレーター =====
* <code>any_x</code> - ''トリガー'' ブロック内で全アイテムを走査し、''すべて'' のアイテムで条件が true なら true を返します。
<code>any_x</code> は <code>count</code> と <code>percent</code> を <code>< <= = != > >=</code> と組み合わせて、true を返すアイテムの数を指定できます。
例:<syntaxhighlight lang="c">
any_living_character = {
count > 10
has_culture = culture:english
is_adult = yes
}
</syntaxhighlight>これは、英語文化の成人が10人より多いことをチェックします。
<code>any_</code> イテレーター内で <code>limit</code> を使わないでください。すでにトリガーだからです。また、ここでは効果を使わないでください。
<code>every_ruler</code>、<code>every_province</code> など、多くのイテレーターがあります。<code>any</code> は triggers.log、<code>every, random, ordered</code> は effects.log を検索してください。
ヒント: すべての <code>every*county</code> イテレーターを見つけるには、正規表現検索（検索パネルの <code>.*</code> ボタン）を有効にし、<code>every_.*county -</code> を検索してください。
<code>every_realm_border_county, every_connected_county, every_title_to_title_neighboring_and_across_water_county</code> などが見つかります。
===== リストイテレーター =====
リストを走査するには次を使います:
* <code>every_in_list, every_in_local_list, every_in_global_list</code>
* <code>ordered_in_list, ordered_in_local_list, ordered_in_global_list</code>
* <code>random_in_list, random_in_local_list, random_in_global_list</code>
* <code>any_in_list, any_in_local_list, any_in_global_list</code>
単純リストか変数リストかを <code>list = name</code> または <code>variable = name</code> で指定します。
== テンプレート ==
==== スクリプト化効果（scripted effects） ====
同じコードを何度も書かないために、scripted effect と呼ばれるテンプレートを作成できます。
使用されると、その内容がスクリプトに貼り付けられるのと同じになります。
定義場所:
* common/scripted_effects（グローバルに使用可能）
* イベントファイル（そのイベント内限定）
common/scripted_effects 内の定義:
<code>my_effect = { add_gold = 100 }</code>
スクリプトでの使用:
<code>my_effect = yes</code>
こうすると <code>add_gold = 100</code> になります。
イベント内では、最初に <code>scripted_effect</code> キーワードを付けます。<syntaxhighlight lang="c">
scripted_effect convert_family = {
every_close_family_member = {
set_character_faith = faith:adamites
}
}
</syntaxhighlight>使用法は同じ: <code>convert_family = yes</code>
これにより、近親者全員がアダマイト派に改宗されます。
==== 置換（Substitution） ====
使用時に置き換えられるパラメータを定義することもできます。
挿入箇所を示すには $$ を使い、任意の名前を付けます:
<code>gift = { add_gold = $val$ }</code>
使用時には、その名前を他のものに置き換えます:
<code>gift = { val = 100 }</code>
スクリプト上では <code>add_gold = 100</code> になります。
この方法で効果の一部など、あらゆる部分を置き換えられます:
<code>my_iterator = { every_$WHO$ = { add_gold = 10 } }</code>
次のように使用します:
<code>my_iterator = { WHO = child }</code>
使用時には <code>every_child = { add_gold = 10 }</code> になります。
スクリプトの塊全体を挿入することもできます:
<code>do_anything = { $DO$ }</code>
<code>do_anything = { DO = "add_gold = 100" }</code>
注意: $$ は scripted effect の定義側でのみ使い、使用側では使わないでください。
パラメータは大文字にするのが慣例で、コード中で見分けやすくなります。ただし必須ではありません。
==== スクリプト化トリガー（scripted triggers） ====
scripted triggers も scripted effects とほぼ同様に動作します。
使用されると、その内容がスクリプトに貼り付けられます。
common/scripted_triggers あるいはイベントファイル内で定義し、イベントファイルでは <code>scripted_trigger</code> を前に付けます
<code>my_trigger = { is_ai = yes }</code>
使用: <code>my_trigger = yes</code>
呼び出し時に <code>= no</code> を使って、偽かどうかをチェックすることもできます。
<code>my_trigger = no</code> は <code>NOT = { my_trigger = yes }</code> と同じです。
置換は scripted triggers でも機能します。
==== スクリプト値（Script values） ====
スクリプト値は計算を実行し、値を返すことができます。
common/script_values で定義:<syntaxhighlight lang="c">
my_value = {
add = age
add = 10
divide = 5
}
</syntaxhighlight>使用: <code>add_gold = my_value</code>
UI では次のように表示できます:
<code>"[GetPlayer.MakeScope.ScriptValue('my_value')]"</code>
変数とは異なり、ここでは GetValue を使わない点に注意してください。
スクリプト値は使用されるたびに計算を行うため、''非常に'' 複雑な計算だとラグの原因になります。
特にUIでは、毎フレーム再計算されるため注意が必要です。
== 回避策 ==
==== 他アプリとの情報交換 ====
デバッグログやエラーログを使用して情報を書き出せます。例えば:
<code>error_log = "Event fired for [ROOT.Char.GetName]"</code>
検索しやすいように文字列に識別子を含めます。例: <code>"<value> [GetPlayer.MakeScope.Var('test').GetValue]"</code>
その後、サードパーティアプリがログを読み込み、その識別子を含む文字列を検索し、データに基づいて処理を実行できます。
情報を取り込むには、<code>run/</code> フォルダ（あなたのmodフォルダの隣）を使用できます。
そこにゲームスクリプトが書かれたテキストファイルを作成し、コンソールコマンド <code>run filename.txt</code> で、プレイヤーを root として実行できます。
UI は <code>ExecuteConsoleCommand</code> 関数でコンソールコマンドを実行できるため、ボタンやアニメーション状態から自動実行させることも可能です。
ただし、コンソールコマンドは実績を無効化するため、プレイヤーに警告してください！
==== 配列（Arrays） ====
次のいずれかを使って、複数の値を保持する「コンテナ」を持つリストを作成できます:
* プロヴィンス
* [[Story cycles modding|ストーリーサイクル]]
プロヴィンスは追加のセットアップを必要とせず、9000件あるため、大規模なリストを作っても「コンテナ」不足の心配はありません。
ストーリーサイクルは必要に応じて作成でき、自動的に効果を実行できるため、より堅牢な解決策ですが、セットアップに手間がかかります。
基本的な手順は次のとおりです:
# 変数リストにコンテナを追加する
# そのコンテナに変数を設定する
# リストを使用し、各アイテム内の変数を参照する
スクリプト文法の詳細は、他のドキュメントページを参照してください:
{{Modding navbox}}
[[Category:Modding]]
※2025/10/6、英wikiよりkagi翻訳を通しました。機械翻訳なので一部不自然な日本語があるかもしれません。ぜひ編集してくれるとありがたいです。
※一部表示が破壊されているところがあります。
'''スクリプト'''は、開発者が許可した範囲で、独自のスクリプト言語を使ってゲームのコンテンツを追加・変更できる仕組みです。
読みやすく、add_gold や set_variable のような名前を用います。
'''スクリプトは common/ と events/ フォルダで使用されます。'''
これは決断、インタラクション、アクティビティ、さらに宗教・文化・伝承などの定義にも拡張されます。
スクリプトではないもの:
* AI や軍の挙動の大部分はゲームコードで処理されており、モッダーからはアクセスできません。このような機能を「ハードコードされている」と呼びます。
* [[Interface|UI]] は別システムであり、いくつかの例外を除き、UI でスクリプトを使ったり、スクリプト内で UI の関数を使ったりはできません。UI でスクリプトを実行するには [[Interface#Scripted GUIs|Scripted GUIs]] を使ってください。
* [[History modding]] も少し異なる静的な仕組みを使いますが、スクリプトのエフェクトを利用できます。
== 基本 ==
ここではスクリプト言語全体のクイックガイドを示します。
==== ドキュメント ====
ゲーム内コンソールの <code>script_docs</code> コマンドを使うと、利用可能な関数一覧のログを生成できます。
ログは <code>Documents\Paradox Interactive\Crusader Kings III\logs</code> に作成されます。
特に、effects、triggers、event_targets のログを確認してください。
そこには次の3つの一般的な関数の種類が列挙されています:
* '''effects''' - <code>add_gold</code> のように何かを実行します。<code>immediate = {}、effect = {}、on_accept = {}</code> のようなエフェクトブロックで使用します。
* '''triggers''' - <code>is_ai = yes</code> のように条件を判定して真偽値を返します。値を返すものもあります。<code>limit = {}、trigger = {}</code> などのトリガーブロックで使用します。
* '''event targets''' - 別のゲームオブジェクトを選択します。例えば <code>primary_heir</code> は後継者を選びます。これらのオブジェクトを「スコープ」と呼び、それらの切り替えを「スコーピング」と呼びます。
logs フォルダにはエラーやデバッグのログもあり、エラーの発見やスクリプトのテストに役立ちます。
フォルダ内には .info ファイルもあり、各ファイルの文法が記載されています。
==== 制限事項 ====
* オペレーティングシステムへのアクセスは不可
* 1次元配列
* 文字列操作は不可
* インライン計算は不可
* 実際のゲームコードより遅い
下記の [[Scripting#Workarounds|回避策]] にいくつかの解決方法があります。
==== スクリプト言語の名称 ====
このスクリプトで使われている言語に公式名称はなく、単に「Paradox スクリプト言語」と呼ばれます。
ただし、[[forum:1170261|Jomini]] ツール群のライブラリが作られた際の更新にちなんで、開発者の一部は「Jomini スクリプト」と呼び始めています。
「Clausewitz」はゲームエンジンの名称です。
==== テスト ====
スクリプトを手早くテストする方法がいくつかあります:
* コンソールで effect または trigger という語を前につければ、短いスクリプトを実行できます。例:
<code>effect add_gold = 100</code> や <code>trigger is_ai = yes</code>
* エクスプローラーのスクリプトランナーを使う（コンソールコマンド <code>explorer</code>）
* run/ フォルダに .txt ファイルでスクリプトを置き、コンソールコマンド <code>run filename.txt</code> で実行
* <code>-develop</code> 起動オプションでゲームを実行し、イベントや決断を即時リロード
エラーログを開いたままにして問題を確認しましょう。コンソールコマンド <code>release_mode</code> でゲーム内にエラートラッカーを表示します。
<code>-debug_mode</code> 起動オプションでゲームを立ち上げ、コンソールを使用します。
スクリプトの検証には有志の [https://github.com/amtep/ck3-tiger CK3 Tiger]（VS Code 向け拡張あり）を利用できます。
== 基本 ==
=== 構文 ===
多くのスクリプトは次の構造に従います:
<code>x = y</code>
<code>x = { y = z }</code><syntaxhighlight lang="c">
x = {
a = b
e = {
f = g
}
}
</syntaxhighlight>例:
* <code>is_alive = yes</code>
* <code>add_gold = 100</code>
* <code>debug_log = "hello world"</code>
* <code>player_heir = { marry = root }</code>
エフェクトやトリガーは単体では使わず、必ず別のパラメータを伴います。単に <code>= yes</code> の場合もあります。
トリガーは <code>= no</code> で否定をチェックすることもできます。
<code>is_ai = no</code> は <code>NOT = { is_ai = yes }</code> と同じです。
値を判定するトリガーは、その値を返すこともあります。
<code>add_gold = age</code> は、キャラクターの年齢に等しい金額を加算します。
<code>target</code> を持つ複雑なトリガーには、丸括弧でターゲットを指定する特別な構文があります:
<code>add_gold = "opinion(liege)"</code>
ここでは引用符が必要です。
=== スコープ ===
スコープとは、キャラクターや伯爵領などのゲーム内の实体です。
エフェクトやトリガーは、適切なスコープで使用する必要があります
* 例: <code>age</code> トリガーはキャラクターに対してのみ機能します。
イベントターゲットによって、あるスコープから別のスコープへ切り替えられます。これをスコーピングと呼びます。
* <code>primary_heir</code> はイベントターゲットで、キャラクターでのみ使用でき、主要後継者を返します。
対応スコープはログで確認してください。
なお、イベントターゲットはどこでも使え、イベント専用ではありません。
=== 連鎖（チェイニング） ===
スコープは <code>x.y.z</code> のように連鎖できます。
<code>primary_heir.faith.religious_head</code> は次と同じです:<syntaxhighlight lang="c">
primary_heir = {
faith = {
religious_head = { }
}
}
</syntaxhighlight>
=== 接頭辞 ===
文化・信仰・宗教・称号・キャラクターを直接参照するには、<code>culture:</code> のような特別な接頭辞が必要です。例:
<code>set_culture = culture:english</code>
<code>set_character_faith = faith:orthodox</code>
<code>capital_county = title:c_byzantion</code>
<code>marry = character:123456</code>
<code>english</code> のようなキーはファイルで、キャラクター ID はデバッグツールチップで探してください。
=== 整形 ===
波括弧内のスクリプトは「コードブロック」と呼ばれます。
インデント（行頭のタブ）は実行には影響しません。理論上は、ほとんどのスクリプトを1行にまとめても動作します。
しかし可読性のため、各コードブロックは1段階ずつインデントしましょう。これにより、どこで開閉しているかが見やすくなり、エディタでブロックを折りたためます。
コメントは # を先頭につけます。
'''例外'''
on_actions の events のように、対になるパラメータなしで複数の要素を受け付けるブロックがあります。例:<syntaxhighlight lang="c">
on_death = {
events = {
death_management.0096
death_management.0097
death_management.0098
}
}
</syntaxhighlight>
== キーワード ==
<code>root</code> - スクリプトの根本にある、スクリプトが実行されている対象。
イベントでは、<code>root</code> はそのイベントを受け取ったキャラクターです。
そのイベント内では、どこでも <code>root</code> が同じキャラクターを参照します。
例: <code>primary_heir = { set_relation_grudge = root }</code>
<code>prev</code> - スクリプト内の直前のスコープ<syntaxhighlight lang="c">
primary_heir = {
primary_spouse = {
set_relation_soulmate = prev
}
}
</syntaxhighlight>ここでは、後継者の配偶者がその後継者のソウルメイトになります。
<code>prevprev</code> は存在せず、1つ前にしか戻れない点に注意してください。
<code>prev = { prev = {</code> のように2回使うと、元のスコープに戻ります。
<code>this</code> - 現在のスコープを参照します。
多くの場合不要ですが、次のようなケースでは便利です:<syntaxhighlight lang="c">
county.holder = {
OR = {
this = root
this = root.primary_spouse
}
}
</syntaxhighlight>
== 演算子 ==
==== 論理演算子 ====
スクリプトには以下があります:
AND, OR, NOT, NOR, NAND
使用例:<syntaxhighlight lang="c">
OR = {
is_ai = yes
gold > 100
}
</syntaxhighlight>これは、そのキャラクターが AI である、または所持金が 100 を超える場合に真になります。
ブロック内には複数のパラメータを置け、<code>OR = { AND = { NOT = {...</code> のように入れ子にもできます。
'''AND''' は全ての条件が真なら真。
'''OR''' はいずれかの条件が真なら真。
'''NOT''' と '''NOR''' は実際には同じで、全ての条件が偽なら真。
'''NAND''' はいずれかの条件が偽なら真。
<code>limit = {}</code> のようなトリガーブロックは、デフォルトで AND として動作し、複数のパラメータを受け付けます。
可読性のため、演算子は大文字で書くのが一般的です（必須ではありません）。
==== 関係演算子 ====
スコープの比較には <code>=</code> を使います。例: <code>primary_heir = primary_spouse</code>。
<code>!=</code> は不等（<code>NOT = { x = y }</code> と同じ）。
値の比較には <code>< <= = != > >=</code> を使います。
<code>?=</code> は特殊な演算子で、そのオブジェクトが存在するかを確認してから比較やスクリプト実行を行います。
<code>capital_county ?= title:c_byzantion</code> は、まずそのキャラクターに首都伯爵領があるかを確認します。次と同じです:<syntaxhighlight lang="c">
exists = capital_county
capital_county = title:c_byzantion
</syntaxhighlight>これにより未設定スコープによるエラーを避け、スクリプトを簡潔にできます。
== 保存スコープ ==
保存スコープは変数に似ています。
あるオブジェクトを保存して後で参照でき、そのスクリプトの実行中のみ存在します。
<code>save_scope_as = name</code>
<code>scope:name = { # 何かを行う }</code><syntaxhighlight lang="c">
primary_heir = { save_scope_as = my_son }
scope:my_son = { death = natural }
</syntaxhighlight>保存スコープは、同じスクリプトから呼ばれる他のイベントやスクリプト化エフェクトにも引き継がれますが、スクリプト全体の実行が終わると消えます。
<code>save_scope_value_as</code> は値や文字列フラグを保存でき、同じ方法で参照します。<syntaxhighlight lang="c">
save_scope_value_as = {
name = cost
value = primary_heir.age
}
add_gold = scope:cost
</syntaxhighlight><syntaxhighlight lang="c">
save_scope_value_as = {
name = kill_locale
value = flag:tower
}
if = {
limit = { scope:kill_locale = flag:tower }
# 何かを行う
}
</syntaxhighlight>
トリガー内では <code>save_temporary_scope_as</code> と <code>save_temporary_scope_value_as</code> を使ってください。
通常版はそこで動作しません。
一部の保存スコープは、on_actions やキャラクターインタラクション内でゲーム側があらかじめ用意しています。
例えばインタラクションでは、<code>scope:actor</code> はインタラクションを開始したキャラクター、<code>scope:recipient</code> は対象キャラクターです。
on_actions については、そのファイル内のコメントに利用可能な保存スコープが記載されています。
重要: イベントターゲットや <code>root</code>、<code>prev</code> のようなキーワードの前に <code>scope:</code> を付けないでください。
<code>scope:</code> は、あなたやゲームが以前に保存した保存スコープにのみ使用します！
== 変数 ==
変数は値を保持するコンテナです。
変数には、数値・キャラクター・ブール値・文字列フラグなど、ほぼ何でも保持できます。
データ型の宣言は不要です。数値変数は固定小数点です。例:<syntaxhighlight lang="c">
set_variable = {
name = test
value = 10
}
</syntaxhighlight><code>var:</code> で値を取得します。
<code>add_gold = var:test</code>
<code>marry = var:my_crush</code>
<code>set_variable = test</code> のように、変数は簡単に設定できます。これは <code>value = yes</code> で変数を設定するのと同じです。
変更には <code>change_variable</code>、削除には <code>remove_variable</code> を使います。例:
<code>change_variable = { name = test add = 1 }</code> と <code>remove_variable = test</code>
ここでは var: を使わず、変数名だけを記述する点に注意してください！
value フィールドは拡張でき、複数の change_variable を使わずに計算できます:<syntaxhighlight lang="c">
set_variable = {
name = test
value = {
add = 10
divide = 5
subtract = 1
}
}
</syntaxhighlight>
格納方法に応じて、変数にはいくつかの種類があります:
* '''通常'''（<code>set_variable</code>）- エフェクトを使用した[[Scopes|スコープ]]に保存されます。アクセスするには、まずそのオブジェクトにスコープを移す必要があります。
** <code>var:</code> で参照します。<code>primary_heir.var:my_sons_birthday</code> のようにチェインも可能。
** キャラクターに保存した場合、そのキャラクターが死亡すると失われます！その場合は死者変数を使用してください。
* '''グローバル'''（<code>set_global_variable</code>）- グローバルに保存され、どこからでも参照できます。もちろん、同名のグローバル変数は一つだけ存在できます。
** <code>global_var:</code> で参照します。
* '''ローカル'''（<code>set_local_variable</code>）- スクリプト実行中のみ存在する一時変数で、どのオブジェクトにも保存されません。
** <code>local_var:</code> で参照します。カウンターとして有用な場合がありますが、使用頻度は低めです。
* '''死者'''（<code>set_dead_character_variable</code>）- 死亡キャラクターに保存され、一定期間後に削除されます。これはパフォーマンス上の理由です。
** <code>dead_var:</code> で参照します。<code>change_</code> エフェクトはありません。
グローバルとローカルには、変更・削除用の固有エフェクトがあります:
<code>change_global_variable</code>、<code>remove_global_variable</code> および <code>change_local_variable</code>、<code>remove_local_variable</code>
UI とローカライズでは、変数は次のように表示できます:
<code>"[GetPlayer.MakeScope.Var('test').GetValue]"</code> - プレイヤーに設定された通常変数の値（数値）を返します。
変数が別のキャラクターを保持している場合は GetValue の代わりに GetCharacter を使います。他の型も同様です。
グローバル変数は次のように表示します:
<code>"[GetGlobalVariable('test').GetValue]"</code>
詳しくは [[Variables]] および [[Interface#Displaying a variable or script value|UI に変数やスクリプト値を表示する]] を参照してください。
== ステートメント ==
==== if / else / else_if ====
limit = {} が true を返したときに効果を実行します。<syntaxhighlight lang="c">
if = {
limit = { is_ai = no }
add_gold = 100
}
</syntaxhighlight>これは、そのキャラクターがAIでない場合にのみゴールドを追加します。
limit が false のときは、<code>if</code> ブロックの直後に <code>else</code> を使って別の効果を実行できます。その効果に別の条件を追加するには <code>else_if</code> を使います。<syntaxhighlight lang="c">
if = {
limit = {
# condition
}
# effect
}
# optional
else_if = {
limit = { #condition }
# effect
}
else = {
# effect
}
</syntaxhighlight>複数の <code>else_if</code> を続けて使用できます。
注意点:
<code>limit</code> は AND ブロックのように動作するため、AND を使わなくても複数の条件を入れられます。
効果は必ず <code>if</code> の中、<code>limit</code> の外に置いてください。ここは間違えやすいポイントです。
==== switch ====
同じトリガーに対して多数の else_if をチェックしている場合は、switch に置き換えられます。
switch は、トリガーの値に一致する効果を1つ選びます。<syntaxhighlight lang="c">
switch = {
trigger = #some trigger
#value = { #effect }
#value = { #effect }
...
}
</syntaxhighlight>例:<syntaxhighlight lang="c">
switch = {
trigger = has_culture
culture:english = { add_gold = 10 }
culture:french = { add_gold = 20 }
culture:italian = { add_gold = 30 }
}
</syntaxhighlight>これは次と同一です:<syntaxhighlight lang="c">
if = {
limit = { has_culture = culture:english }
add_gold = 10
}
else_if = {
limit = { has_culture = culture:french }
add_gold = 20
}
else_if = {
limit = { has_culture = culture:italian}
add_gold = 30
}
</syntaxhighlight>
==== while ループ ====
<code>while</code> はアクションを複数回繰り返すために使います。
<code>count</code> を使えば所定回数、<code>limit</code> を使えば条件が false になるまで実行を続けられます。
例:<syntaxhighlight lang="c">
while = {
count = 10
add_gold = 100
}
while = {
limit = { gold > 0 }
remove_short_term_gold = 50
}
</syntaxhighlight><code>while</code> はデフォルトで1000回に制限されており、誤って無限ループになるのを防ぎます。
ループを途中で抜ける方法はありません。
==== trigger_if / trigger_else / trigger_else_if ====
<code>trigger_if</code> は <code>limit</code> ブロックが true の場合にのみトリガーをチェックします。false の場合、そのチェックはスキップされます。
例: キャラクターがAIでない場合に、独立した支配者かどうかをチェックします。
trigger_if = {
limit = { is_ai = no }
is_independent_ruler = yes
}
<code>trigger_else_if</code> は、if/else と同様に <code>trigger_if</code> の後に使用できます。<syntaxhighlight lang="c">
trigger_if = {
limit = { ... }
...
}
trigger_else_if = {
limit = { ... }
...
}
trigger_else = {}
</syntaxhighlight>スクリプトによっては、最後に trigger_else が必要な場合があります。うまく動かないときは追加してみてください。
<code>trigger_if</code> はトリガーブロック内でのみ使用し、効果内では使わないようにしてください。
== リスト / 配列 ==
リストは、変数と同様に、複数のオブジェクト、変数、文字列フラグを保持できます。
リストは他のリストを保持できません。
リストには一時的なものと永続的なものの2種類があります。
UI は変数リストやグローバル変数リストのような永続リストを表示できます。参照: [[Interface#Displaying data lists|Interface/Displaying_data_lists]]
ややこしいことに、ローカル変数リストは永続ではありません。
リストを作るには、以下のコマンドのいずれかで各アイテムを追加します:
'''一時:'''
* <code>add_to_list</code> - 単純なリストに追加します。スクリプト実行中にのみ存在します
* <code>add_to_local_variable_list</code> - 似ていますが、一定期間後にリストから削除される「期間」をアイテムに付与できます
* <code>add_to_temporary_list</code> - 他と異なり、トリガーブロック内でも使用できます
'''永続:'''
* <code>add_to_variable_list</code> - 効果が実行されたスコープに保存されるリストへ追加します。期間をサポート
* <code>add_to_global_variable_list</code> - グローバルな永続リストへ追加します。期間をサポート
リストがまだ存在しない場合、これらのコマンドのいずれかがリストを作成し、アイテムを追加します。
すでにアイテムがリストにある場合、重複はしません。
正しい文法は effects.log を参照してください。
<code>add_to_variable_list</code> は紛らわしい文法である点に注意してください。
そのリストを保持するスコープで効果を実行し、ターゲット側では実行しないようにしてください。
イテレーターではよく次のように使います。まず root にスコープしてリストをそこに保存し、次に直前のスコープをターゲットとして追加します。<syntaxhighlight lang="c">
every_ruler = {
root = {
add_to_variable_list = {
name = rulers
target = prev
}
}
}
</syntaxhighlight>
リストにアイテムが入っているかをチェックするには:
<code>is_in_list, is_target_in_variable_list, is_target_in_global_variable_list, is_target_in_local_variable_list</code>
アイテムを削除するには:
<code>remove_from_list, remove_list_variable, remove_list_local_variable, remove_list_global_variable</code>
単純なリストを一括クリアする効果はありません。クリアできるのは変数リストのみです:
<code>clear_variable_list, clear_global_variable_list, clear_local_variable_list</code>
単純なリストをクリアするには、リストを走査して各アイテムを削除してみてください。
ほとんどの場合、リストを作る前に <code>clear_variable_list</code> を実行し、再作成時に古いアイテムが残らないようにします。
存在しないリストをクリアしようとしてもエラーにはなりません。
<code>*_list_size</code> トリガーはサイズをチェックできますが、その値を返すことはできません。
サイズを値として使う必要がある場合は、リストを走査してアイテム数を数えてください。スクリプト値が役に立ちます。common/script_values の .info ファイルを参照してください。
== イテレーター ==
イテレーターは一連のアイテムを走査し、各アイテムに対して効果やトリガーを実行します。
例:<syntaxhighlight lang="c">
every_ruler = {
limit = { age > 20 }
add_gold = 100
}
</syntaxhighlight>これは20歳より上のすべての支配者に100ゴールドを追加します。
<code>limit = {}</code> は任意です。false を返した場合、その効果は実行されません。
<code>every_living_character = { every_province = {</code> のようなことはしないでください。9000の州を、存命キャラクター2万人分だけ繰り返すことになり、ラグの原因になります。
===== 効果イテレーター =====
これらはアイテムに対して何らかの効果を実行し、''効果'' ブロック内でのみ使用できます:
* <code>every_x</code> - 追加された順に全アイテムを走査
* <code>ordered_x</code> - <code>age</code> のような値で並べ替え。全件走査または1件選択が可能
* <code>random_x</code> - ランダムに1件選択。確率は調整可能
===== トリガーイテレーター =====
* <code>any_x</code> - ''トリガー'' ブロック内で全アイテムを走査し、''すべて'' のアイテムで条件が true なら true を返します。
<code>any_x</code> は <code>count</code> と <code>percent</code> を <code>< <= = != > >=</code> と組み合わせて、true を返すアイテムの数を指定できます。
例:<syntaxhighlight lang="c">
any_living_character = {
count > 10
has_culture = culture:english
is_adult = yes
}
</syntaxhighlight>これは、英語文化の成人が10人より多いことをチェックします。
<code>any_</code> イテレーター内で <code>limit</code> を使わないでください。すでにトリガーだからです。また、ここでは効果を使わないでください。
<code>every_ruler</code>、<code>every_province</code> など、多くのイテレーターがあります。<code>any</code> は triggers.log、<code>every, random, ordered</code> は effects.log を検索してください。
ヒント: すべての <code>every*county</code> イテレーターを見つけるには、正規表現検索（検索パネルの <code>.*</code> ボタン）を有効にし、<code>every_.*county -</code> を検索してください。
<code>every_realm_border_county, every_connected_county, every_title_to_title_neighboring_and_across_water_county</code> などが見つかります。
===== リストイテレーター =====
リストを走査するには次を使います:
* <code>every_in_list, every_in_local_list, every_in_global_list</code>
* <code>ordered_in_list, ordered_in_local_list, ordered_in_global_list</code>
* <code>random_in_list, random_in_local_list, random_in_global_list</code>
* <code>any_in_list, any_in_local_list, any_in_global_list</code>
単純リストか変数リストかを <code>list = name</code> または <code>variable = name</code> で指定します。
== テンプレート ==
==== スクリプト化効果（scripted effects） ====
同じコードを何度も書かないために、scripted effect と呼ばれるテンプレートを作成できます。
使用されると、その内容がスクリプトに貼り付けられるのと同じになります。
定義場所:
* common/scripted_effects（グローバルに使用可能）
* イベントファイル（そのイベント内限定）
common/scripted_effects 内の定義:
<code>my_effect = { add_gold = 100 }</code>
スクリプトでの使用:
<code>my_effect = yes</code>
こうすると <code>add_gold = 100</code> になります。
イベント内では、最初に <code>scripted_effect</code> キーワードを付けます。<syntaxhighlight lang="c">
scripted_effect convert_family = {
every_close_family_member = {
set_character_faith = faith:adamites
}
}
</syntaxhighlight>使用法は同じ: <code>convert_family = yes</code>
これにより、近親者全員がアダマイト派に改宗されます。
==== 置換（Substitution） ====
使用時に置き換えられるパラメータを定義することもできます。
挿入箇所を示すには $$ を使い、任意の名前を付けます:
<code>gift = { add_gold = $val$ }</code>
使用時には、その名前を他のものに置き換えます:
<code>gift = { val = 100 }</code>
スクリプト上では <code>add_gold = 100</code> になります。
この方法で効果の一部など、あらゆる部分を置き換えられます:
<code>my_iterator = { every_$WHO$ = { add_gold = 10 } }</code>
次のように使用します:
<code>my_iterator = { WHO = child }</code>
使用時には <code>every_child = { add_gold = 10 }</code> になります。
スクリプトの塊全体を挿入することもできます:
<code>do_anything = { $DO$ }</code>
<code>do_anything = { DO = "add_gold = 100" }</code>
注意: $$ は scripted effect の定義側でのみ使い、使用側では使わないでください。
パラメータは大文字にするのが慣例で、コード中で見分けやすくなります。ただし必須ではありません。
==== スクリプト化トリガー（scripted triggers） ====
scripted triggers も scripted effects とほぼ同様に動作します。
使用されると、その内容がスクリプトに貼り付けられます。
common/scripted_triggers あるいはイベントファイル内で定義し、イベントファイルでは <code>scripted_trigger</code> を前に付けます
<code>my_trigger = { is_ai = yes }</code>
使用: <code>my_trigger = yes</code>
呼び出し時に <code>= no</code> を使って、偽かどうかをチェックすることもできます。
<code>my_trigger = no</code> は <code>NOT = { my_trigger = yes }</code> と同じです。
置換は scripted triggers でも機能します。
==== スクリプト値（Script values） ====
スクリプト値は計算を実行し、値を返すことができます。
common/script_values で定義:<syntaxhighlight lang="c">
my_value = {
add = age
add = 10
divide = 5
}
</syntaxhighlight>使用: <code>add_gold = my_value</code>
UI では次のように表示できます:
<code>"[GetPlayer.MakeScope.ScriptValue('my_value')]"</code>
変数とは異なり、ここでは GetValue を使わない点に注意してください。
スクリプト値は使用されるたびに計算を行うため、''非常に'' 複雑な計算だとラグの原因になります。
特にUIでは、毎フレーム再計算されるため注意が必要です。
== 回避策 ==
==== 他アプリとの情報交換 ====
デバッグログやエラーログを使用して情報を書き出せます。例えば:
<code>error_log = "Event fired for [ROOT.Char.GetName]"</code>
検索しやすいように文字列に識別子を含めます。例: <code>"<value> [GetPlayer.MakeScope.Var('test').GetValue]"</code>
その後、サードパーティアプリがログを読み込み、その識別子を含む文字列を検索し、データに基づいて処理を実行できます。
情報を取り込むには、<code>run/</code> フォルダ（あなたのmodフォルダの隣）を使用できます。
そこにゲームスクリプトが書かれたテキストファイルを作成し、コンソールコマンド <code>run filename.txt</code> で、プレイヤーを root として実行できます。
UI は <code>ExecuteConsoleCommand</code> 関数でコンソールコマンドを実行できるため、ボタンやアニメーション状態から自動実行させることも可能です。
ただし、コンソールコマンドは実績を無効化するため、プレイヤーに警告してください！
==== 配列（Arrays） ====
次のいずれかを使って、複数の値を保持する「コンテナ」を持つリストを作成できます:
* プロヴィンス
* [[Story cycles modding|ストーリーサイクル]]
プロヴィンスは追加のセットアップを必要とせず、9000件あるため、大規模なリストを作っても「コンテナ」不足の心配はありません。
ストーリーサイクルは必要に応じて作成でき、自動的に効果を実行できるため、より堅牢な解決策ですが、セットアップに手間がかかります。
基本的な手順は次のとおりです:
# 変数リストにコンテナを追加する
# そのコンテナに変数を設定する
# リストを使用し、各アイテム内の変数を参照する
スクリプト文法の詳細は、他のドキュメントページを参照してください:
{{Modding navbox}}
[[Category:Modding]]