Engine02 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:
| 21 | (D) (E) | Func_Set_Palette_Range |
| 823 | (D) (E) | Func_Restore_Global_Palette |
Palette Settings:
| 41 | (D) (E) | Func_Palette_Effect |
| 91 | (D) (E) | Func_Switch_Palette |
Descriptions:
Color Setting:
21 - Func_Set_Palette_Range
(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- Set Current and Target palette, accounting for "water"
1- Set Current palette, accounting for "water"
2- Set Target palette, accounting for "water"
3- Set Current and Target palette, ignoring "water"
4- Set Current palette, ignoring "water"
5- Set Target palette, ignoring "water"
6- Set Current, Target, and Global palette, accounting for "water"
7- Set Current and Global palette, accounting for "water"
8- Set Target and Global palette, accounting for "water"
9- Set Current, Target, and Global palette, ignoring "water"
10- Set Current and Global palette, ignoring "water"
11- 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.
Because Windows uses values 0-255 for each component, but DOS uses
only 0-64 (the same color range. The extra colors in Windows are
padding, each group of 4 values are actually the same), there are
two different ways to set up the colors. If the color value comes
from the Windows-style 0-255 color range, use the label "W". If it comes from
the DOS-style 0-64 color range, use the label "D". (Ex. "D32" or "W128", both
are the same value)
1438 - Func_Set_PaletteAlpha_Range
(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- Set Current and Target palette, accounting for "water"
1- Set Current palette, accounting for "water"
2- Set Target palette, accounting for "water"
3- Set Current and Target palette, ignoring "water"
4- Set Current palette, ignoring "water"
5- Set Target palette, ignoring "water"
6- Set Current, Target, and Global palette, accounting for "water"
7- Set Current and Global palette, accounting for "water"
8- Set Target and Global palette, accounting for "water"
9- Set Current, Target, and Global palette, ignoring "water"
10- Set Current and Global palette, ignoring "water"
11- 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.
Because Windows uses values 0-255 for each component, but DOS uses
only 0-64 (the same color range. The extra colors in Windows are
padding, each group of 4 values are actually the same), there are
two different ways to set up the colors. If the color value comes
from the Windows-style 0-255 color range, use the label "W". If it comes from
the DOS-style 0-64 color range, use the label "D". (Ex. "D32" or "W128", both
are the same value)
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
1439 - Func_Dim_Palette_Range
(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:
823 - Func_Restore_Global_Palette
(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 "Set_Palette_Range", because the purpose of those
settings are to permanantly modify the Global Palette itself.
Parameters:
- ActiveFlag
This flag determines whether the on-screen palette is changed, or
only the fade target palette is affected.
0 - Target Palette is changed, Current Palette is not
1 - Target Palette and Current Palette are both changed
Palette Settings:
41 - Func_Palette_Effect
(ALL) (Example)
Initiates a special effect on the Current Palette, as listed below
Parameters:
- Effect
The palette effect that should be initiated:
1- Fade in (to Target Palette colors)
2- Fade out to black
3- Fade out to white
4- Instantly set all colors to black
5- Instantly set all colors to white
6- Instantly set all colors to the Target Palette
7- One-step Fade toward Target Palette colors
8- One-step Fade toward black
9- 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
91 - Func_Switch_Palette
(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
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 - Target palette is changed, Current Palette is not
1 - Target palette and On-Screen palette are both changed
Examples:
# 21 ;Set_Palette_Range (Set Current and Target indexes 192-193 with "Windows Style" 0-255 colors)
: 3 ;(Type) Current, Target, no Water
: 192 ;(Start)
: 2 ;(Num Indexes)
:W128 ;(Red) 192
:W 96 ;(Green)
:W 0 ;(Blue)
:W192 ;(Red) 193
:W192 ;(Green)
:W 0 ;(Blue)
; ----------
# 21 ;Set_Palette_Range (Set Current and Target indexes 64-66 with "DOS Style" 0-63 colors, accounting or "water")
: 0 ;(Type) Current, Target, Water
: 64 ;(Start)
: 3 ;(Num Indexes)
:D 32 ;(Red) 64
:D 24 ;(Green)
:D 0 ;(Blue)
:D 48 ;(Red) 65
:D 48 ;(Green)
:D 0 ;(Blue)
:D 56 ;(Red) 66
:D 56 ;(Green)
:D 0 ;(Blue)
1438 - Func_Set_PaletteAlpha_Range
(Description)
# 21 ;Func_Set_PaletteAlpha_Range (Apply a dark blue alpha to Current and Target indexes 244-248, based on "Windows Style" 0-255 colors)
: 3 ;(Type) Current, Target, no Water
: 244 ;(Start)
: 5 ;(Num Indexes)
:W 0 ;(Red)
:W 0 ;(Green)
:W128 ;(Blue)
; ----------
# 21 ;Func_Set_PaletteAlpha_Range (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")
: 0 ;(Type) Current, Target, Water
: 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
1439 - Func_Dim_Palette_Range
(Description)
#1439 ;Dim Palette_Range (Dim Target indexes 128-255 to half of their current brightness)
: 5 ;(Type) Target, no Water
: 128 ;(Start)
: 128 ;(Num Indexes)
: 64 ;(Percentage) Dim to half of current brightness
; ----------
# 21 ;Dim Palette_Range (Dim Current and Target indexes 0-64 by the amount given by User Register 6, accounting for Water)
: 0 ;(Type) Current, Target, Water
: 0 ;(Start)
: 64 ;(Num Indexes)
: R6 ;(Percentage) Value stored in User Register 6
823 - Func_Restore_Global_Palette
(Description)
# 823 ;Restore_Global_Palette (Restore the Global Palette colors immediately)
: 1 ;(Flag) Target and Current
; ----------
# 823 ;Restore_Global_Palette (Restore the Global Palette colors for fade-in)
: 0 ;(Flag) Target Only
Palette Settings:
# 41 ;Palette_Effect (Fade Current Palette colors to the Target Palette colors, halting gameplay until finished)
: 1 ;(Effect) Fade To Target
; ----------
# 41 ;Palette_Effect (Fade Current Palette to white, allowing gameplay to continue during the fade)
: -3 ;(Effect) Fade To White (no pause)
; ----------
# 41 ;Palette_Effect (Immediately set all Current Palette colors to black)
: -2 ;(Effect) Instant Black
91 - Func_Switch_Palette
(Description)
# 91 ;Switch_Palette (Switch to Level Palette 1, don't affect Current Palette until fade-in)
: 1 ;(PalID)
: 0 ;(Flag) Target Only
; ----------
# 91 ;Switch_Palette (Switch to Level Palette 0, update on-screen colors immediately)
: 0 ;(PalID)
: 1 ;(Flag)Target and Current