Headcannon Game Engine Script Commands - Palette
These Commands are used for manipulating the Palette.
For the purpose of Scripted control, there are thee different forms in which the Palette may be modified:
- "Current Palette" - The full list of 256 colors that are currently being used to draw the screen
- "Target Palette" - A "copy" of the full palette that is used as the target colors for fade-in. It can be modified independently of the "Current Palette"
- "Global Palette" - In this documentation, this refers to the backup of the colors that were loaded as the "Global Palette" section. This backup is used to restore these colors to their defaults if they were modified in the "Current Palette"
Index:
Color Setting:
(D) (E) | _Pal_SetRange |
(D) (E) | _Pal_SetIndex_Reg |
(D) (E) | _Pal_RestoreGlobal |
(D) (E) | _Pal_LoadNewGlobal |
Color Manipulation:
(D) (E) | _Pal_FadeEffect |
(D) (E) | _Pal_DimRange |
(D) (E) | _Pal_SetAlphaRange |
Palette Setting:
(D) (E) | _Pal_Switch |
(D) (E) | _Pal_Switch_OneScreen |
Descriptions:
Color Setting:
_Pal_SetRange
(ALL) (Example)
Set a range of colors on the palette. The desired palette range is given by the
starting index, and the total number of indexes to modify. This command can
modify the "Current palette" and/or the "Target palette",
and can accomodate for "water" by modifying the "water"-equivalant index (index + 128) in
the palette if desired. The "Global Palette", which remains the same
from level to level, may also be permanently modified when writing to its section of the
Current/Target palette to prevent loss of any new colors if it is ever restored.
Parameters:
- Set Type
This value tells the script how the given palette indices should
be set:
0 | - | _PalSet_Current_Target_Water | - | Set Current and Target palette, accounting for "water" |
1 | - | _PalSet_Current_Water | - | Set Current palette, accounting for "water" |
2 | - | _PalSet_Target_Water | - | Set Target palette, accounting for "water" |
3 | - | _PalSet_Current_Target | - | Set Current and Target palette, ignoring "water" |
4 | - | _PalSet_Current | - | Set Current palette, ignoring "water" |
5 | - | _PalSet_Target | - | Set Target palette, ignoring "water" |
6 | - | _PalSet_Current_Target_Global_Water | - | Set Current, Target, and Global palette, accounting for "water" |
7 | - | _PalSet_Current_Global_Water | - | Set Current and Global palette, accounting for "water" |
8 | - | _PalSet_Target_Global_Water | - | Set Target and Global palette, accounting for "water" |
9 | - | _PalSet_Current_Target_Global | - | Set Current, Target, and Global palette, ignoring "water" |
10 | - | _PalSet_Current_Global | - | Set Current and Global palette, ignoring "water" |
11 | - | _PalSet_Target_Global | - | Set Target and Global palette, ignoring "water" |
- Start Index
This is the first index at which the given colors should be inserted
- Num of Indexes
This is the number of colors that will be applied to the palette, starting
at the given start index. Each color is then listed below in this way:
- Red
- Green
- Blue
These are the Red, Green, and Blue components of the desired color.
They have a range of 0-255 (8-bit component values)
_Pal_SetIndex_Reg
(ALL) (Example)
Set a single color entry on the palette using an index and component values stored in Game Registers, allowing
for effects that require runtime calculation of the target palette index and color components. This command can
modify the "Current palette" and/or the "Target palette",
and can accomodate for "water" by modifying the "water"-equivalant index (index + 128) in
the palette if desired. The "Global Palette", which remains the same
from level to level, may also be permanently modified when writing to its section of the
Current/Target palette to prevent loss of any new colors if it is ever restored.
Parameters:
- Set Type
This value tells the script how the given palette indices should
be set:
0 | - | _PalSet_Current_Target_Water | - | Set Current and Target palette, accounting for "water" |
1 | - | _PalSet_Current_Water | - | Set Current palette, accounting for "water" |
2 | - | _PalSet_Target_Water | - | Set Target palette, accounting for "water" |
3 | - | _PalSet_Current_Target | - | Set Current and Target palette, ignoring "water" |
4 | - | _PalSet_Current | - | Set Current palette, ignoring "water" |
5 | - | _PalSet_Target | - | Set Target palette, ignoring "water" |
6 | - | _PalSet_Current_Target_Global_Water | - | Set Current, Target, and Global palette, accounting for "water" |
7 | - | _PalSet_Current_Global_Water | - | Set Current and Global palette, accounting for "water" |
8 | - | _PalSet_Target_Global_Water | - | Set Target and Global palette, accounting for "water" |
9 | - | _PalSet_Current_Target_Global | - | Set Current, Target, and Global palette, ignoring "water" |
10 | - | _PalSet_Current_Global | - | Set Current and Global palette, ignoring "water" |
11 | - | _PalSet_Target_Global | - | Set Target and Global palette, ignoring "water" |
- Reg Dest Index
This is the index at which the given color should be inserted
- Reg Red
- Reg Green
- Reg Blue
These are the ID numbers of the Game Registers that contain the values
to be used the Red, Green, and Blue components of the desired color.
The component values are expected to be 8-bit (0-255).
_Pal_RestoreGlobal
(ALL) (Example)
Restores the colors from the "Global Palette" if the On-Screen "Current Palette" equivalants had been
modified. The colors may be copied to the "Target Palette", or both the Current
and Target Palettes. This will not, however, restore colors that were changed using
"Set Type" 8 or greater with "Pal_SetRange" to their original state, because the purpose of those
settings are to permanantly modify the Global Palette itself. The same applies to use of the _Pal_LoadNewGlobal Command
Parameters:
- ActiveFlag
This flag determines whether the on-screen palette is changed, or
only the fade target palette is affected.
0 | - | _PalSwitch_TargetOnly | - | Target palette is changed, Current Palette is not |
1 | - | _PalSwitch_Current | - | Target palette and On-Screen palette are both changed |
_Pal_LoadNewGlobal
(ALL) (Example)
Loads new colors into the "Global Palette" from the image file whose name is specified by the given Game/Zone Text, permanently replacing any that were loaded previously.
This cannot be undone by the _Pal_RestoreGlobal Command, as the purpose of this Command is to redefine the "restorable" color set.
Parameters:
- Text ID
ID number of the Text string that contains the filename of the
data to load. This ID references Text from a Game Def
or a Zone Def. The "G" and "Z" tags may be used to reference "Game" and "Zone" Texts, respectively
The filename in the Text string must be relative to the "Program Folder", not to the folder that contains
the file in which it appears.
Color Manipulation:
_Pal_FadeEffect
(ALL) (Example)
Initiates a special effect on the Current Palette, as listed below
Parameters:
- Effect
The palette effect that should be initiated:
-3 | - | _PalFade_ToWhite_NoFreeze | - | Fade out to white (Gameplay continues normally throughout fade) |
-2 | - | _PalFade_ToBlack_NoFreeze | - | Fade out to black (Gameplay continues normally throughout fade) |
-1 | - | _PalFade_ToTarget_NoFreeze | - | Fade in (to Target Palette colors) (Gameplay continues normally throughout fade) |
0 | - | Invalid | - | Invalid |
1 | - | _PalFade_ToTarget | - | Fade in (to Target Palette colors) (Gameplay is suspended during fade) |
2 | - | _PalFade_ToBlack | - | Fade out to black (Gameplay is suspended during fade) |
3 | - | _PalFade_ToWhite | - | Fade out to white (Gameplay is suspended during fade) |
4 | - | _PalFade_SetBlack | - | Instantly set all colors to black |
5 | - | _PalFade_SetWhite | - | Instantly set all colors to white |
6 | - | _PalFade_SetTarget | - | Instantly set all colors to the Target Palette |
7 | - | _PalFade_ToTarget_Once | - | One-step Fade toward Target Palette colors |
8 | - | _PalFade_ToBlack_Once | - | One-step Fade toward black |
9 | - | _PalFade_ToWhite_Once | - | One-step Fade toward white |
Fade effects 1-3 cause the game to pause until the
effect is finished. To allow the game to process while the fade
is in effect, negate the effect ID number (IE: "-1" instead of "1")
The "One-step" effects will fade toward the specified colors by the amount
that effects 1-3 fade on one Game Frame, and must be called several times
in succession to cause a complete fade. They may be used to manually create
slower than normal fade effects, as well as partial fades
_Pal_DimRange
(ALL) (REG) (Example)
Dim (or brighten) a range of colors on the palette by the given percentage.
The desired palette range is given by the
starting index, and the total number of indexes to modify. This command can
modify the "Current palette" and/or the "Target palette",
and can accomodate for "water" by modifying the "water"-equivalant index (index + 128) in
the palette if desired. The "Global Palette", which remains the same
from level to level, may also be permanently modified when writing to its section of the
Current/Target palette to prevent loss of any new colors if it is ever restored.
Note: This applies to the current state of the colors. Once dimmed/brightened, their original state is lost
Parameters:
_Pal_SetAlphaRange
(ALL) (REG) (Example)
Perform an "alpha blend" on the given palette range against the given color.
The desired palette range is given by the
starting index, and the total number of indexes to modify. This command can
modify the "Current palette" and/or the "Target palette",
and can accomodate for "water" by modifying the "water"-equivalant index (index + 128) in
the palette if desired. The "Global Palette", which remains the same
from level to level, may also be permanently modified when writing to its section of the
Current/Target palette to prevent loss of any new colors if it is ever restored.
Note: This applies to the current state of the colors. Once the alpha is applied, their original state is lost
Parameters:
- Set Type
This value tells the script how the given palette indices should
be affected:
0 | - | _PalSet_Current_Target_Water | - | Set Current and Target palette, accounting for "water" |
1 | - | _PalSet_Current_Water | - | Set Current palette, accounting for "water" |
2 | - | _PalSet_Target_Water | - | Set Target palette, accounting for "water" |
3 | - | _PalSet_Current_Target | - | Set Current and Target palette, ignoring "water" |
4 | - | _PalSet_Current | - | Set Current palette, ignoring "water" |
5 | - | _PalSet_Target | - | Set Target palette, ignoring "water" |
6 | - | _PalSet_Current_Target_Global_Water | - | Set Current, Target, and Global palette, accounting for "water" |
7 | - | _PalSet_Current_Global_Water | - | Set Current and Global palette, accounting for "water" |
8 | - | _PalSet_Target_Global_Water | - | Set Target and Global palette, accounting for "water" |
9 | - | _PalSet_Current_Target_Global | - | Set Current, Target, and Global palette, ignoring "water" |
10 | - | _PalSet_Current_Global | - | Set Current and Global palette, ignoring "water" |
11 | - | _PalSet_Target_Global | - | Set Target and Global palette, ignoring "water" |
- Start Index
This is the first index at which to apply the alpha
- Num of Indexes
This is the number of colors that will be affected, starting
at the given start index
- Red
- Green
- Blue
These are the Red, Green, and Blue components of the desired alpha.
They have a range of 0-255 (8-bit component values)
The r and R tags may also be used to retrieve these components from Registers.
The values stored in the Registers must be "DOS-style", 0-64
Palette Setting:
_Pal_Switch
(ALL) (REG) (Example)
Sets the currently-active "Level Palette" based on the palettes that were
loaded with the most recently-loaded Tile File. If this is done during an
Act's "Init Function", only the "Target Palette" should be set, and the
selected palette will be displayed when a palette fade-in effect is used.
If it is done at any other time, the change can be made to take place immediately if
desired. This is controlled by the ActiveFlag Parameter
This Command affects all active player screens. If only one player's screen should switch Level Palettes,
the _Pal_Switch_OneScreen" Command must be used instead.
Parameters:
- Palette ID
ID number of the palette that should be used for display.
A Register may be used for this value, including the
"Curr_Palette" (r51) register, if the currently-selected
palette should be refreshed
- ActiveFlag
This flag determines whether the on-screen palette is changed, or
only the fade target palette is affected. The new palette's
animation will begin immediately if the "FreezeObjects" flag
register (r2) is not set to 1.
0 | - | _PalSwitch_TargetOnly | - | Target palette is changed, Current Palette is not |
1 | - | _PalSwitch_Current | - | Target palette and On-Screen palette are both changed |
_Pal_Switch_OneScreen
(ALL) (REG) (Example)
Sets the currently-active "Level Palette" based on the palettes that were
loaded with the most recently-loaded Tile File. If this is done during an
Act's "Init Function", only the "Target Palette" should be set, and the
selected palette will be displayed when a palette fade-in effect is used.
If it is done at any other time, the change can be made to take place immediately if
desired. This is controlled by the ActiveFlag Parameter
This Command affects only one active player screen. If all player's screens should switch Level Palettes,
the _Pal_Switch" Command may be used instead.
Parameters:
- Palette ID
ID number of the palette that should be used for display.
A Register may be used for this value, including the
"Curr_Palette" (r51) register, if the currently-selected
palette should be refreshed
- Screen ID
ID number of the player screen whose Level Palette should be switched.
A Register may be used for this value, including the
"Curr_Player" (r9) register, if the Command is used
during a Function triggered directly by a Player, such as a Boundary Event.
- ActiveFlag
This flag determines whether the on-screen palette is changed, or
only the fade target palette is affected. The new palette's
animation will begin immediately if the "FreezeObjects" flag
register (r2) is not set to 1.
0 | - | _PalSwitch_TargetOnly | - | Target palette is changed, Current Palette is not |
1 | - | _PalSwitch_Current | - | Target palette and On-Screen palette are both changed |
Examples:
#_Pal_SetRange ;Set Current and Target indexes 192-193
:_PalSet_Current_Target ;(Type)
: 192 ;(Start)
: 2 ;(Num Indexes)
: 128 ;(Red) 192
: 96 ;(Green)
: 0 ;(Blue)
: 192 ;(Red) 193
: 192 ;(Green)
: 0 ;(Blue)
_Pal_SetIndex_Reg
(Description)
#_Pal_SetIndex_Reg ;Set the Current and Target palette entry whose ID is stored in User Register 32 to the color whose Red, Green, and Blue component values are stored in User Registers 33, 34, and 35, respectively
:_PalSet_Current_Target ;(Type)
: U32 ;(Index)
: U33 ;(Red)
: U34 ;(Green)
: U35 ;(Blue)
_Pal_RestoreGlobal
(Description)
#_Pal_RestoreGlobal ;Restore the Global Palette colors immediately
:_PalSwitch_Current ;(Flag)
; ----------
#_Pal_RestoreGlobal ;Restore the Global Palette colors for fade-in
:_PalSwitch_TargetOnly ;(Flag)
_Pal_LoadNewGlobal
(Description)
#_Pal_LoadNewGlobal ;Load new Global Palette colors from the image file whose name is given by "Game" Text 2
: G2 ;(Text ID) "Game" Text 2
; ----------
#_Pal_LoadNewGlobal ;Load new Global Palette colors from the image file whose name is given by "Game" Text whose ID is stored in User Register 4
: R4 ;(Text ID) Value stored in User Register 4
Color Manipulation:
#_Pal_FadeEffect ;Fade Current Palette colors to the Target Palette colors, halting gameplay until finished
:_PalFade_ToTarget ;(Effect)
; ----------
#_Pal_FadeEffect ;Fade Current Palette to white, allowing gameplay to continue during the fade
:_PalFade_ToWhite_NoFreeze ;(Effect)
; ----------
#_Pal_FadeEffect ;Immediately set all Current Palette colors to black
:_PalFade_SetBlack ;(Effect)
_Pal_DimRange
(Description)
#_Pal_DimRange ;Dim Target indexes 128-255 to half of their current brightness
:_PalSet_Target ;(Type)
: 128 ;(Start)
: 128 ;(Num Indexes)
: 64 ;(Percentage) Dim to half of current brightness
; ----------
#_Pal_DimRange ;Dim Current and Target indexes 0-64 by the amount given by User Register 6, accounting for Water
:_PalSet_Current_Target_Water ;(Type)
: 0 ;(Start)
: 64 ;(Num Indexes)
: R6 ;(Percentage) Value stored in User Register 6
_Pal_SetAlphaRange
(Description)
#_Pal_SetAlphaRange ;Apply a dark blue alpha to Current and Target indexes 244-248
:_PalSet_Current_Target ;(Type)
: 244 ;(Start)
: 5 ;(Num Indexes)
: 0 ;(Red)
: 0 ;(Green)
: 128 ;(Blue)
; ----------
#_Pal_SetAlphaRange ;Apply an alpha to Current and Target indexes 32-39 based on the colors whose component values are stored in User Registers 2-4, accounting or "water"
:_PalSet_Current_Target_Water ;(Type)
: 32 ;(Start)
: 8 ;(Num Indexes)
: R2 ;(Red) Value stored in User Register 2
: R3 ;(Green) Value stored in User Register 3
: R4 ;(Blue) Value stored in User Register 4
Palette Setting:
#_Pal_Switch ;Switch all active player screens to Level Palette 1, don't affect Current Palette until fade-in
: 1 ;(PalID)
:_PalSwitch_TargetOnly ;(Flag)
; ----------
#_Pal_Switch ;Switch all active player screens to Level Palette 0, update on-screen colors immediately
: 0 ;(PalID)
:_PalSwitch_Current ;(Flag)
_Pal_Switch_OneScreen
(Description)
#_Pal_Switch_OneScreen ;Switch Player Screen 0 to Level Palette 2, don't affect Current Palette until fade-in
: 2 ;(PalID)
: 0 ;(ScreenID)
:_PalSwitch_TargetOnly ;(Flag)
; ----------
#_Pal_Switch_OneScreen ;Switch the Player Screen whose ID is stored in "User Register" 5 to the Level Palette whose ID is stored in "User Register" 6, update on-screen colors immediately
: R5 ;(PalID)
: R6 ;(ScreenID)
:_PalSwitch_Current ;(Flag)