===================
``\explosions.ini``
===================

Chess EXTREME uses ``explosions.ini`` as definitions for the various explosion animations used and to know what piece uses what.

Piece Codes
===========

Each key has two identifiers, the colour and the name of the piece.

``W - P``

``W = White``

``P = Pawn``

Due to this formatting, some pieces have the same first character as another and use a different one instead:

``Knight = N``

Otherwise, use the first character in a piece's name and you should be good.

With each piece of each side having its own definition you can use this with custom skins to make some pretty nice looking custom graphics. Currently it's only the normal chess pieces but if you wanted to you could make a Halo skin pack for example, where the UNSC has normal explosions while the Covenant have their plasma explosions. 

``[PIECE_EXPLOSIONS]``
======================

More than likely the first section you will find in ``explosions.ini`` is ``[PIECE_EXPLOSIONS]``

.. code-block:: text
    :caption: This is the default.

    [PIECE_EXPLOSIONS]
    ; White pieces
    WP=EXPLOSION_SMALL
    WR=EXPLOSION_MEDIUM
    WN=EXPLOSION_MEDIUM
    WB=EXPLOSION_MEDIUM
    WQ=EXPLOSION_LARGE
    WK=EXPLOSION_LARGE

    ; Black pieces
    BP=EXPLOSION_SMALL
    BR=EXPLOSION_MEDIUM
    BN=EXPLOSION_MEDIUM
    BB=EXPLOSION_MEDIUM
    BQ=EXPLOSION_LARGE
    BK=EXPLOSION_LARGE

This is a simple list of definitions that tie a explosion animation to a specific chess piece. 

``[EXPLOSIONS]``
================

After examining ``[PIECE_EXPLOSIONS]``, you will then come across numerous defined explosions with various keys. 

In order to change existing explosions or create new ones, you will have to understand how to define them:

.. code-block:: text
    :caption: This is the explosion used for Pawns.

    [EXPLOSION_SMALL]
    spritesheet=Sprites\ExplosionSmall.png ; spritesheet = Path to the sprite sheet image file (relative to ChessExtreme.exe)
    frame_width=28 ; frame_width = Width of each frame in pixels
    frame_height=24 ; frame_height = Height of each frame in pixels
    num_frames=14 ; num_frames = Total number of animation frames in the sprite sheet
    layout=vertical ; layout = Sprite sheet orientation: "horizontal" (default) or "vertical"
    offset_x=10 ; offset_x = Horizontal offset from center position (default: 0)
    offset_y=0 ; offset_y = Vertical offset from center position (default: 0)
    scale=2.0 ; scale = Scale multiplier for the sprite (default: 1.0)
    fps=30 ; fps = Frames per second for animation speed (default: 60)

.. warning::
    Make sure to have the backgrounds on your sprite sheets be completely black as it will be automatically removed. 
    Transparent colours are rendered, so if you are exporting sprites from a game, replace the shadow colour with a 50% black instead. 
    You can freely add or remove explosions as long as you assign it to the pieces.

``[NUKE_FINISH]``
=================

This is the only explosion that cannot be renamed or replaced, as this is hardcoded to be read only for the nuke finish.

.. code-block:: text
    :caption: The explosion used in the nuke finish.

    [NUKE_FINISH]
    spritesheet=Sprites\Nuke.png
    frame_width=78
    frame_height=121
    num_frames=27
    layout=vertical
    offset_x=0
    offset_y=0
    scale=3.0
    fps=30