Other Common Command Formats

This page collects parameter formats reused by many story commands. When a command parameter says “item list”, “weather effect”, “global position”, or a similar shared format, look it up here.

Text Colors and Images

Dialogue boxes, text boxes, and some common UI can use double brackets to assign colors to text. Custom colors use & in place of #.

This is [[imp:important text]], [[&ff6699ff:custom colored text]]

Color Code	Use	Color Value	Preview
place	Place name	#a32121
role	Role name	#a32121
camp	Faction name	#a32121
item	Item name	#a32121
imp	Important information	#a32121
quest	Quest information	#00ffff
mag_damage	Magic damage	#4489a3
phy_damage	Physical damage	#bf3b25
effect	Effect feedback	#9a52a0
explain	Explanation text	#b55e1f
recover	Recovery text	#6b9f52
desc	Description text	#9d9150

Images can also be inserted into dialogue. Common forms:

[[img:image path,size=size format]]
[[img:ui://NewUI/defence_1,size=1.8em]]
[[img:ui://NewUI/defence_1,height=50%,width=50%]]

Path Type	Format	Example
Assets resource path	Assets/resource path	Assets/BuildSource/headavata/unknown_man-head.png
FairyGUI URL	ui://package/resource	ui://NewUI/defence_1
Role portrait	role://RoleID	role://主角
Custom portrait	avatar://character:PortraitID	avatar://character:unknown_man
Dynamic model	model://3D#ModelID#ActionID#ExtraInfo	model://3D#雷电男1#男长枪1#r_weapon:weaponSpear1;l_weapon:null
Common model, weapon	model://Model#Weapon#WeaponPrefabID	model://Model#Weapon#weaponSpear1
Common model, building	model://Model#Building#BuildingPrefabID	model://Model#Building#building_fort_1
Game effect	model://Effect#EffectPrefabID	model://Effect#psChestFlash1

Dynamic model paths usually follow model://. Standard role models use 3D#ModelID#ActionID#ExtraInfo; $ can also be used instead of #. Weapon prefabs are under Assets/BuildSource/weapon_models/Prefabs/, building prefabs are under Assets/BuildSource/buildings/, and effect prefabs are under Assets/BuildSource/battle_effects/.

model://3D#雷电男1#男长枪1#r_weapon:weaponSpear1;l_weapon:null
model://Model#Weapon#weaponSpear1
model://Model#Building#building_fort_1
model://Effect#psChestFlash1

Size Form	Description
height=64	Uses a pixel value.
height=100%	Scales by percentage of the original image size.
height=2em	Scales by the current line-height multiplier.
size=1em	Fits height to one line-height and scales width proportionally.

Position Format

Roles, teams, world-map objects, and teleport commands use position formats. When filling a position, first confirm whether the parameter expects a role position or a world-map coordinate.

Role positions use:

PositionCode:PositionParam

Format	Description
0	No assigned position.
1:PlaceID,FacilityID	The role is in a place. If the facility ID is empty, the role is outside facilities.
2:TeamID	The role is in a team.
3:ProjectID	The role is in a project.
MapID:CoordX,CoordY	Global position for a world-map object or team, commonly used by commands such as TELEPORT.

When a world-map object, team, teleport command, or similar parameter needs a global position, use the map and coordinates directly:

MapID:CoordX,CoordY

Specific Battle Unit Restrictions

Restriction conditions in a specific battle table can combine multiple command fields separated by semicolons.

command1:param1;command2:param2;...commandN:paramN;

Command	Description
player	Resets the team hero list. Format: RoleID1,ResetLevel|RoleID2,ResetLevel|...; reset level -1 or empty means do not reset.
units	Resets the team’s common soldier list, using the normal card list format.
add_stat	Adds role attribute states. Format: TargetRoleID#StatusTable.

World-Map Unit Control Command Table

World-map unit control commands assign a sequence of behaviors to a team. The unit executes each command in order. If the game is saved in the middle, loading the save continues the unfinished commands. Except for special units such as dummies and monsters, most teams disband automatically when their command table ends.

1,test_map:100,100;1,test_map:100,200;99,0

Code	Description
1	Move to a world-map coordinate. Parameter: MapID:CoordX,CoordY.
2	Stay in place. Parameter: stay duration in in-game days.
3	Enter a place. Parameter: target place ID.
4	Attack a target place. Parameter: PlaceID,CaptureMode; 0 occupies, 1 plunders.
5	Stay inside the target place. Parameter: PlaceID,StayDuration.
7	Execute an event. Parameter: event ID.
8	Change the current StateNum value. Parameter: new StateNum.
9	Permanently execute a custom movement command.
10	Join a warband. Parameter: warband numeric ID.
11	Play an action. Parameters: action ID, loop count, single action duration, playback object, initial frame range, and whether to continue to the next command after playback ends.
12	Plunder a place. Parameter: target place ID. This code is deprecated.
13	Open a chest. Parameter: chest ID.
14	Execute a TimeLine action. Parameter: TimeLineID,Duration; duration defaults to -1, meaning continuous playback.
15	Change the current team’s attitude toward the player. 0 neutral, 1 hostile.
16	Change the current team’s movement speed. Parameter: target speed.
17	Mark a trade as successful. Parameter: trade target place ID.
18	Perform a trade. Parameter: trade target place ID.
19	Follow a target team. Parameter: target team’s control ID.
99	Disband the current team.

StateNum can mark the current state of a story-controlled team, such as 0 before reaching a position and 1 after arrival, then triggers or queries can use that value for later behavior.

The 5th parameter of an action command is the initial frame range, from 0-1. 1 means the last animation frame, and -1 picks a random frame. The 6th parameter controls whether playback continues into the next command; the default is 0, and 1 continues to the following command.

Default action IDs can use loop actions and one-shot actions. Loop actions include idle, move, walk slowly, charge, and charge-up. One-shot actions include hit reaction, dodge, block, attack, shoot, horizontal slash, downward slash, thrust, release, roar, knock-up, jump, celebrate, and death.

Default Movement Command Format for Units and Teams

Dummies, monsters, and teams on the world map can set default movement modes. Scripts can also temporarily change movement modes. After a mode is assigned, the unit follows that mode as its default behavior.

MovementMode,param1[,param2,...,paramN]

Movement Mode	Description
WANDER,radius[,centerX,centerY]	Wander within the specified radius. If center coordinates are omitted, the unit’s current position is used as the center.
PATROL,x1,y1,x2,y2,...,xN,yN	Patrol between multiple coordinate points. If the first coordinate equals the last coordinate, patrol loops; otherwise it goes back and forth.
Other value or empty	Stay still.

Item Lists

Item lists use compact string parameters. Multiple items are separated by |, and fields within one item are separated by commas.

ItemCode1,count1[,detailInfoTable]|ItemCode2,count2[,detailInfoTable]|...|ItemCodeN,countN[,detailInfoTable]

This format is used by item or resource lists in commands such as GETITEMS, REMOVE_ITEMS, and LOOT. The detail info table uses a key=value dictionary format, with multiple fields separated by English commas.

Field	Description
mf	Automatically match and create affixes. Format: mf=minQuality-maxQuality[-variableValueBase]; minimum quality 0 means an affix may be omitted.
cw	Create a specified affix. Format: cw=AffixID+variableValueBase; the variable value base is usually 0-100.
w	Specifies complete affix details. Format: w=AffixID$variableCodeArray.
qv	Specifies an item attribute variable array.
p	Records the item’s purchase price.

长剑,1,mf=0-3
长剑,1,cw=吸血剑+50

Variable code arrays are written as enumValue/qualityValue pairs. For example, an affix with 3 variables can be written as 0/50/0/100/0/100.

Weather Effects

Weather effects combine multiple effects with |. Within one effect, the weather ID and intensity are separated by a comma.

WeatherEffectID,intensity|WeatherEffectID2,intensity

Intensity 0 turns an effect off. For rain and snow, 1-50 means normal rain or snow, and 50-100 means heavy rain or heavy snow. Sandstorm, lightning, fog, and darkness use 1-100.

Weather Effect ID	Intensity
雨	0 off, 1-50 normal rain, 50-100 heavy rain.
雪	0 off, 1-50 normal snow, 50-100 heavy snow.
风沙	0 off, 1-100 intensity.
雷电	0 off, 1-100 intensity.
雾	0 off, 1-100 intensity.
黑暗	0 off, 1-100 intensity.
炎热	0 off, 1-100 heat distortion intensity.
云	0 off, 1-100 ground cloud-shadow intensity in clear weather.

Random Weather

chance,durationDays:weatherEffect;chance,durationDays:weatherEffect

Example:

30,1:;50,3:雨,20|雾,10;20,5:风沙,30

This means: 30% chance of no weather effect for 1 day; 50% chance of rain with fog for 3 days; 20% chance of sandstorm for 5 days.

Camera Filters

FilterEffectID,intensity|FilterEffectID2,intensity

Supports vignette, black-and-white, and old-photo effects. Intensity 0 turns the effect off, and 1-100 controls effect strength.

Filter Effect ID	Intensity
暗角	0 off, 1-100 edge darkening strength.
黑白	0 off, 1-100 black-and-white photo effect strength.
老旧	0 off, 1-100 yellowed old-photo effect strength.

Special Fields in the Role Table

Some role table fields create special effects in story, battle, or UI. When filling these fields, prefer the fixed field names shown in the table.

Field	Description
LIKE	Marks item types the role likes, affecting favor gain speed. Format: LIKE:type1|type2|....
DEF_WEAPON_SPEED	Default weapon speed used when the role has no equipped weapon.
FVChangeUnit	Algorithm unit coefficient used when gifts change role favor.
dg_skill	Replaces this role’s dungeon skill.
attached_script	Script event ID attached to this role in battle.
loot_list	Drop list for this role in dungeon battle; 经验 can be used as an item ID to specify an EXP source.
IsNoExpel	Prevents expelling this role; active when the field is not empty.
IsNoBetray	This role will not betray or leave a faction on its own; active when the field is not empty.
CanChangeName	Allows story triggers to change the name; active when set to 1, and does not affect direct name changes by script commands.

Special Fields in the Place Table

Field	Description
迷你地图显示	Shows the minimap for places other than town maps, which display by default.
迷你地图不显示	Hides the minimap.
AI出征关闭	The stronghold will not proactively march, patrol, or occupy resource points.
SharedPermission	Place ID whose trade permission is shared.

After SharedPermission is configured, this place shares trade permission with the specified place.

Special Fields in the Faction Table

Field	Description
NO_CHANGE_DIP	Not affected by dynamic diplomacy changes, except direct script command changes.
UNFAILED	The faction cannot be destroyed through normal means.
EMBARGO	Places occupied by the faction will not send caravans and will not trade with other places.
NO_FARMER	Places occupied by the faction will not have population movement.
CAMP_COLOR	Specifies faction color. Example: CAMP_COLOR=FFFFFF.
CAMP_UI_BG	Specifies the faction info UI background.
HIDE_BY_ACTIVESTATE	Hides related information according to the current ActiveState.

If CAMP_COLOR is not specified, the game assigns a default color to the faction. If CAMP_UI_BG is not specified, the faction info screen uses the default background overlaid with the faction color. HIDE_BY_ACTIVESTATE only takes effect when the config table’s “hidden” field does not force hiding.

Special Fields in the Item Table

Field	Description
IgnoreBagSpace	The item does not take inventory space when set to 1.
NoSellOrDrop	The item cannot be discarded or sold when set to 1.
BatchUse	Supports batch use. The used quantity is written into arg_int_val1.
DoNotCostWhenUse	The item is not consumed on use when set to 1.
Present	Gift type tag field, separated with |.
AiNotLoot	AI cannot obtain the item through normal means when set to 1.
Mendable	Whether the item can be repaired; non-repairable items are destroyed automatically when durability reaches 0.
RoleAct	Uses a specified role model action after equipping.
DropModel	Model info for this item on the ground in battle. Format: WorldMapUnitModelID#EffectInfo. If empty, def_dropitem_model from the initial settings table is used.

Special Fields in Exploration Maps

Field	Description
BattleLoseStay	Whether the player stays in place after losing a battle in exploration map mode.
RolePlay	When the player is on this map, replaces the role model and name with specified role info and disables UI such as inventory and party.
FixedGameTime	Freezes the current map time to a specific time of day.
CameraFilter	Forces a specified camera filter when entering the map.
NoFoodConsume	The player does not consume food and will not starve on this map.

FixedGameTime ranges from 0-1.0; for example, 0.5 means 12:00 noon. After time is frozen, world time does not advance, but units on the current map keep acting. CameraFilter uses the same format as camera filters.

Special Fields in Dungeons

Field	Description
PlayerInitType	Player role initialization mode: 0 default mode, using the default role template and dungeon start position; 1 manual mode, controlled through Lua APIs.
ExpMode	EXP distribution mode. Format: distributionMode[,radiusParam].

ExpMode Mode	Description
0	Last-hit mode, the default. The killer alone gains EXP.
1	Equal distribution mode. If the radius parameter is less than or equal to 0, all allied players share EXP equally.
2	Shared distribution mode. If the radius parameter is greater than 0, EXP is shared only within the specified radius.

Item Affixes

Item affixes are reused by multiple systems and are usually written as strings in config tables, command parameters, or effect configs.

Form	Description
AffixType:{enumInfo1,value1;enumInfo2,value2;...}	General affix structure.
a	Passively increases role attributes.
skill	Adds an available role skill.
dg_skill	Replaces the current dungeon skill.

Item Drops

chance1,ItemID1,minCount,maxCount[,paramTable]|chance2,ItemID2,minCount,maxCount[,paramTable]|...|chanceN,ItemIDN,minCount,maxCount[,paramTable]

Example:

100.0,金钱,100,200|50.0,经验,100,200

This means: always gain 100-200 money, and have a 50% chance to gain 100-200 EXP. The parameter table uses the same detail info format as item lists.

Item ID can be the special value QUERY, meaning it queries a drop result from the global drop table and returns it. The parameter table then specifies global drop query conditions.

chance,QUERY,minCount,maxCount[,id=DropID,lv=Level,t1=Tag1,t2=Tag2,t3=Tag3]

Query Parameter	Description
id	Directly takes the result with the specified ID from the global drop table. If present and not empty, other query conditions are ignored.
lv	Matching level. -1 matches all results; 0 uses the main character’s current level.
t1	Filter query TAG1.
t2	Filter query TAG2.
t3	Filter query TAG3.

Effect Object Events

eventTime:commandType,param1,param2,...

The event time is seconds after start. Supports shake_cam and play_sound.

Command Type	Parameters
shake_cam	Parameter 1 is shake duration; parameter 2 is intensity.
play_sound	Parameter 1 is sound ID.