Expanded Drama Actions

Temporary Version

This part of documentation is a partially written stub, and API usages may change at any time.

CWL comes with a small set of built-in drama expansion methods, which you can checkout code here.

This feature requires the CWL configuration value Dialog.ExpandedActions set to true, enabled by default.

In the drama sheet, you can use the CWL special action invoke* or i* for short to call expansion method:

Parameter Passing

Parameters are separated by comma , and written within the parentheses of the expansion method, similar to code syntax:

action	param	actor
invoke*/i*	honk_honk(arg1, arg2)	pc

Most of the methods also take actor cell as the target character to execute the method on, such as pc or tg(the drama owner character), or any valid character id. Default is tg.

If the jump in the same line has any value, then the return value of the expansion method will be used to determine if the jump will be executed. Returns true will execute the jump, otherwise not.

Value Expression: +5, *10, =69, !=114 etc, used to evaluate or assign values.

Actions

method	param	description	jump
add_item	item id, material alias(optional), level(optional), count(optional)	Add the item with id to actor, default random material, auto level, and count of 1	always
equip_item	item id, material alias(optional), level(optional)	Equip the item with id on actor, default random material, auto level	always
join_party		Make actor join player party	always
join_faith	religion id(optional)	Make actor join the specific religion with id or leave the current religion with empty value	if success
apply_condition	condition alias, power	Apply a condition with id to actor, default power 100	always
cure_condition	condition alias	Cure the condition on actor	if cured
remove_condition	condition alias	Remove the condition on actor	always
build_ext	assembly partial name	Attempt to add static methods from assembly to drama expansion table	if success
emit_call	ext.method	Invoke an external static method	always

build_ext and emit_call requires the CWL configuration value Dialog.ExpandedActionsAllowExternal set to true, enabled by default.

Scene Play

method	param	description	jump
move_next_to	character id	Move actor next to character with id on the same map	always
move_tile	x, y	Move actor with relative tile offset, such as 1, 1 or 2, -1	always
move_zone	zone id, level(optional)	Move actor to a specific zone with id, and specific level, default 0	always
play_anime	anime id	Play animation on actor	always
play_effect	effect id	Play effect on actor	always
play_emote	emote id	Play emote on actor	always
play_screen_effect	screen effect id	Play screen effect	always
pop_text	text	Pop a text bubble above actor head	always
portrait_set	portrait id(optional)	Set actor portrait in dialog to the specific one or reset with empty value, from Portrait folder, e.g. UN_myChara_happy.png could be set with happy or UN_myChara_happy	always
show_book	book id, category(Book or Scroll)	Open a book, supports LangMod/**/Text folder, for example Text/Book/ok.txt would use (ok, Book)	If success

Modifications

method	param	description	jump
mod_affinity	value expression	Modify actor affinity with value expression	if success
mod_currency	currency type, value expression	Modify actor currency with value expression. money money2 plat medal influence casino_coin ecopo	always
mod_element	element alias, power(optional)	Modifies a specified element (feat/resistance/skill, etc.) for the actor, default power 1. Different types of elements use different power scaling	always
mod_element_exp	element alias, value expression	Modifies the exp of a specified element for the actor	If success
mod_fame	value expression	Modify player fame with value expression	always
mod_flag	flag, value expression	Modify the flag value from actor with value expression, such as +1, =1, 0. This supports non player character	always
mod_keyitem	keyitem alias, value expression(optional)	Modify player's keyitem value with expression, default =1	if success

Conditions

These are still expansion methods that uses invoke* action same as above, but their return value is important.

method	param	description	jump
if_affinity	value expression	Check actor affinity with expression, such as <5, >=90, !=0	if satisfies
if_condition	condition alias	Check if actor has active condition with alias	if active
if_currency	currency type, value expression	Check actor currency with value expression. money money2 plat medal influence casino_coin ecopo	if satisfies
if_element	element alias, value expression	Check actor element with expression	if satisfies
if_faith	religion id, reward rank(optional)	Check if actor is certain religion and above reward rank, default >0	if satisfies
if_fame	value expression	Check player's fame with value expression	if satisfies
if_flag	flag name, value expression	Check actor flag value with expression, such as =5, 1, !=0	if satisfies
if_keyitem	keyitem alias, value expression(optional)	Check if player has keyitem with expression, default >0	if satisfies
if_race	race id	Check if actor is of certain race	if satisfies
if_tag	tag	Check if actor has certain tag defined in Chara row	if defined
if_zone	zone id, level(optional)	Check if actor is in certain zone and optionally check level	if present

There are 3 special composite conditions where you put the above condition as parameter:

method	example	jump
and	and(if_flag(flag1, >0), if_flag(flag2, <0))	If all satisfies
or	or(if_race(lich), if_race(snail))	If any satisfies
not	not(if_zone(dungeon), if_zone(field), if_zone(underground))	If none satisfies

if_flag or hasFlag?

hasFlag in if column is a static condition, which only gets evaluated once on drama load, which means your flag value changes later won't reflect unless using reload action or reopening the drama. CWL's if_flag() expansion condition is dynamic and can be used for branching.

Implementing Your Own

CWL offers easy API to add expansion methods in your own script DLL, without even needing to reference CWL's script assembly.