Card Battle Arena Docs

Script Editor

The Script Editor is the command language behind Story Mode. It lets an admin add dialogue, condition checks, variables, media, music, sound, animation, and battle control inside the Story Script, Chapter Script, After Battle Script, and Ending Script fields.

Introduction Where it is used Syntax rules Commands Logic and variables Examples Runtime behavior

Back to Story Mode Practical Setup

What the Script Editor is

The editor is line-based. It does not use WordPress shortcodes. Instead, each line is read as a command or dialogue line. Blank lines are ignored, lines starting with # or // are treated as comments, and any line that does not match a command becomes narrator dialogue automatically.

Fast authoringAdmins can paste a scene quickly without building a large nested form.

Flexible controlUse logic, variables, random branches, and media cues in the same scene block.

Story-awareThe runtime knows the active story, the current chapter, and custom variables.

Safe fallbackIf a script is empty, Story Mode falls back to the normal media and dialogue fields.

Where the script runs

Field	When it runs	Typical use
Story Script	Before the first chapter starts.	Opening scene, setup logic, intro cinematic, variable priming.
Chapter Script	Before a chapter battle starts.	Branching decisions, dialogue, battle unlock checks, media cues.
After Battle Script	After a chapter battle finishes.	Victory reactions, story twists, rewards, post-battle media.
Ending Script	After the last chapter finishes.	Final reveal, epilogue, and story closure.

Syntax rules

Write one command per line.
Use uppercase keywords for readability.
Indentation is only visual; the parser uses the command keywords.
Use {{variable_name}} to print stored variables inside dialogue or media values.
Use quotes around values that contain spaces when you compare or assign them.
Use comments with # or // when you want to leave notes for other admins.

Any text that is not a recognized command becomes narrator dialogue, so the editor is forgiving when you need quick script lines.

Command reference

Command	Purpose	Example
`SAY`	Shows speaker dialogue.	`SAY Batman \| The mission starts now.`
`NARRATE`	Shortcut for narrator text.	`NARRATE The city is already on fire.`
`SET`	Stores a custom variable.	`SET hero_ready = 1`
`ADD`	Adds a number to an existing variable.	`ADD score = 10`
`IF` / `ELSE` / `ENDIF`	Creates conditional branches.	`IF hero_series == "Justice Squad"`
`RANDOM` / `ENDRANDOM`	Runs a branch by chance.	`RANDOM \| 25`
`IMAGE`	Displays an image scene.	`IMAGE https://example.com/scene.jpg`
`VIDEO`	Plays a video clip.	`VIDEO https://example.com/intro.mp4`
`WAIT`	Pauses in milliseconds.	`WAIT 1200`
`MUSIC`	Starts or stops background music.	`MUSIC https://example.com/bgm.mp3`
`STOP_MUSIC`	Stops the current story music.	`STOP_MUSIC`
`SOUND`	Plays a one-shot sound effect.	`SOUND https://example.com/hit.wav`
`ANIMATION`	Triggers an animation or effect.	`ANIMATION victory_burst`
`BATTLE`	Requests the battle to begin.	`BATTLE auto`
`STOP`	Stops the script immediately.	`STOP`

For BATTLE, the optional mode can be auto or manual. If no mode is supplied, the chapter or global default is used.

Logic and variables

Condition operators

==, !=
>, <, >=, <=
contains or includes
! for negation
&& and || for combined checks

Values and variables

Quoted strings stay as text.
Numbers are converted into numbers.
true and false are treated as booleans.
Variables created with SET and changed with ADD can be reused later in the same run.

SET phase = 1
IF hero_series == "Ilyana Starfire" && phase == 1
  SAY Ilyana | The frost listens to me.
ENDIF

RANDOM | 30
  SAY Narrator | A surprise branch appears.
ENDRANDOM

Dialogues and media

Dialogue format

The dialogue parser accepts either command lines or simple Speaker: Dialogue text lines. In the admin story fields, that same style is also used for the plain dialogue textareas.

SAY Batman | Stay close.
SAY Batwoman | I am already three steps ahead.
NARRATE The team moves into the dark tower.

Media format

Images and videos accept absolute URLs, root-relative paths, data URLs, and blob URLs. Media lists can also be entered as line-by-line values, and the runtime normalizes arrays or JSON into usable items.

IMAGE https://example.com/scene-01.jpg
VIDEO https://example.com/intro.mp4
MUSIC /wp-content/uploads/story/theme.mp3
SOUND /wp-content/uploads/story/hit.wav
ANIMATION /wp-content/uploads/story/flash.gif

`ANIMATION` can point to a real media file such as GIF, PNG, JPG, WebP, SVG, MP4, WebM, MOV, or M3U8. If you pass a non-file token like victory_burst, the runtime shows a built-in effect card with that name.

Ready-to-use script patterns

Opening scene

SET intro_seen = 1
IMAGE https://example.com/city-night.jpg
SAY Narrator | The city waits in silence.
SAY Batman | We move now.
BATTLE manual

After battle scene

SAY Villain | This is not over.
MUSIC stop
SOUND https://example.com/explosion.wav
ANIMATION defeat_flash
WAIT 800
STOP

How the runtime behaves

Story variables are reset when Story Mode starts.
The Skip button can end dialogue and media sequences early.
In chapter scripts, a skip can jump the scene toward the battle flow.
When the script requests a battle, Story Mode passes control to the battle system.
If a chapter ends and the next chapter is set to Auto Fight, the flow can continue automatically after the configured delay.

Available Variables

The Story Script engine supports built-in context variables and custom variables created with SET or ADD commands.

{{hero_series}} - Active hero series selected for the story or chapter.
{{enemy_series}} - Current enemy series selected for the chapter.
{{story_title}} - Current story title.
{{chapter_title}} - Current chapter title.
{{chapter_number}} - Current chapter index.
{{battle_mode}} - Auto or manual battle mode.
{{player_name}} - Current player name when available.
{{continue_chances}} - Remaining continue attempts.
{{hero_card_count}} - Total number of hero cards available in the current story context.
{{enemy_card_count}} - Total number of enemy cards available in the current story context.
{{hero_card_ids}} - The stored IDs of the hero cards in the current selection.
{{enemy_card_ids}} - The stored IDs of the enemy cards in the current selection.
{{hero_card_names}} - The display names of the hero cards loaded into the scene.
{{enemy_card_names}} - The display names of the enemy cards loaded into the scene.
{{hero_card_summary}} - A short summary of the current hero card set.
{{enemy_card_summary}} - A short summary of the current enemy card set.
{{variable_name}} - Any custom variable created through SET or ADD.

Conditional Variables

IF hero_series == Justice Squad
IF enemy_series == Avengers
IF chapter_number == 3
IF hero_ready == 1
ELSE
ENDIF

Duration Control Variables

These commands let the Script Editor control how long the current Story Mode step stays active before moving on. They apply only to the current script session or the current story section where they are called, such as Intro, Chapter, After Battle, or Ending. They do not change the global timing for other scenes.

SET_DIALOGUE_DURATION | 5000 sets the current dialogue line duration to 5000 milliseconds.
SET_IMAGE_DURATION | 10000 keeps the current image event active for 10000 milliseconds.
SET_VIDEO_DURATION | 750 keeps the current video event active for 750 milliseconds, or until the video ends if the media lasts longer.
SET_ANIMATION_DURATION | 700 controls the current animation event duration for 700 milliseconds.
SET_SOUND_DURATION | 400 controls the current sound event duration for 400 milliseconds when a timed sound step is used.
SET_MUSIC_DURATION | 1000 controls the current music event duration for 1000 milliseconds when a timed music step is used.

If the same duration variable is called again later in the same script, the new value replaces the earlier one for the next event in that current session. This is useful when one Intro needs slower pacing but another Chapter needs faster pacing.

SET_DIALOGUE_DURATION | 5000
SAY Narrator | The room goes silent.

SET_IMAGE_DURATION | 10000
IMAGE https://example.com/scene.jpg

SET_VIDEO_DURATION | 750
VIDEO https://example.com/intro.mp4

SET_ANIMATION_DURATION | 700
ANIMATION victory_flash

SET_SOUND_DURATION | 400
SOUND https://example.com/effect.wav

SET_MUSIC_DURATION | 1000
MUSIC https://example.com/theme.mp3

Use these commands only for the active script section. A later call can override the earlier timing value inside the same story flow, while other sections continue using their own durations.

Complete Command Reference

Command	Purpose
SET variable = value	Create or overwrite a variable.
ADD variable = value	Add numeric value to existing variable.
IF condition	Start conditional block.
ELSE	Alternative branch.
ENDIF	Close conditional block.
RANDOM	Start random event block.
ENDRANDOM	Close random block.
SAY Character \| Dialogue	Display character dialogue.
NARRATE Text	Display narrator text.
IMAGE url	Show image.
VIDEO url	Play video.
MUSIC url	Start background music.
STOP_MUSIC	Stop current music.
SOUND url	Play sound effect.
ANIMATION effect_name	Play animation effect.
WAIT milliseconds	Pause progression.
BATTLE	Launch chapter battle.
STOP	Stop script execution.

Advanced Example

SET hero_ready = 1
SET chapter_reward = 500

IF hero_series == Justice Squad
  SAY Batman | The city depends on us.
  MUSIC https://example.com/batman-theme.mp3
  IMAGE https://example.com/gotham.jpg
ENDIF

RANDOM
  SAY Ironman | Ready for action.
ENDRANDOM

IF hero_ready == 1
  ANIMATION ultimate_physical_2
  SOUND https://example.com/explosion.mp3
  WAIT 2000
  BATTLE
ELSE
  NARRATE The heroes are not prepared.
ENDIF

SAY Narrator | Reward: {{chapter_reward}} coins

Variable Interpolation Examples

SAY Narrator | Welcome to {{story_title}}
SAY Batman | Enemy faction detected: {{enemy_series}}
IMAGE https://site.com/{{hero_series}}.jpg
MUSIC https://site.com/music/{{chapter_number}}.mp3