CARD file format

The CARD file format is a binary file format used to share card informations from the Pulsar Card Editor (PCE) to the Pulsar Game.
You can easily create your cards with the PCE and it is very easy to make it usable in the game. Just "compile" it as a binary file!

Here is a description of the CARD file format. It is a special and open format created for the Pulsar Game.

First of all, the CARD file format contains a header.
There is then a list of the Stars used in the full Card.
Finally, there is the list of links between stars.

Endianness

If you do not know what is endianness, you can read this introduction. Else, you can directly go to the file description (Header, etc).

Endianness can be described as the order of bytes.
A Big Endian computer reads/writes bytes from the most significant byte to the less significant byte.
On the contrary, a Little Endian computer reads/writes bytes from the less significant byte to the most significant byte.

For example, in a classic way we represent hexadecimal integer value : 0x12345678.
A Big Endian computer will read/write : 0x12345678
A Little Endian computer will read/write : 0x78563412

As you can imagine, a Little Endian computer cannot correctly read informations saved by a Big Endian computer, and reversely! We should be aware of a such situation when parsing binary files.

A last one more thing! Float values can also be affected by endianness.
In the default Pulsar Game, the parsers consider that either integers and floats are both Big Endian or Little Endian. No parser considers Big Endian integers and Little Endian floats (as it could happen).
It may also happen that a computer is neither little nor big endian. If you consider an ARM processor, it is middle endian (between little and big endian). In the basic Pulsar Game parsers, there is no middle endian parser.

Header

The header contains different and useful informations.

First, you will find flags to find the way the file should be parsed according to the endianness of the CPU. Indeed, the PCE is written in Java. Yet, the JVM is a Big Endian machine and so output binary files with a different byte order than recent computers. As reversing the endianness of the output file is not a good solution, the parsing step needs to test the endianness of the computer executing the game.

The first two bytes are then a flag to detect endianness on integer values.
The bytes to read are 0x12 and 0x34. It is then the 16-bits value 0x1234.

After that, we have 4 bytes that are a float value. As float and integer values can have different endianness on the same machine, it is interesting to solve the endianness of both types for future versions of the game (with improved parsers to handle different architectures). At the moment, the game integrated parsers can correcly parse files on CPU having the same endianness for the two types (integers and floats).

So, the four next bytes corresponds to the float value 123.456789 (it is then a 32-bits float, not a 64-bits float (also called double)).

Once you have defined the endianness and selected the right parser (the game API contains classes to easily handle parsing), you can start reading card informations.
The next bytes concern the names of the card in different languages. As the Pulsar Game can be available in many languages, card have translations of their name. And as the PCE can be forked and contain more languages than the default version, the game must be able to detect all the languages the card has.

So, the incoming byte is the amount of languages in the card (there is a "limitation" to 255 languages...). We will say that their are N languages in the file.

Then, you can repeat N times the following description.
You will find a 16-bits integer value corresponding to the size of the language ISO 639-1 code (generally it is on 2 characters, so this 16-bits integer value is 2). For example : "en", "fr", "de", "it", "ja"... So, consider that on the "2" following bytes you will have the text corresponding to that code.
https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes

Directly after the ISO code of the language, you have the name of the card in the corresponding language. First of all, the length of the name in bytes. Then the list of the bytes corresponding to the name. It is written in UTF-8, so special characters can take between 2 to 4 bytes (while ASCII characters will be encoded on a single byte). Don't worry, the length is correct even if there are special characters!

Stars description

The Stars description is simple.
The first byte is the amount of used Stars in the card, let's call it S. You can then iterate on this S number to parse the file.

You will find S times the following informations :
- One byte containing the Star index ;
- One byte containing the type of Star (Defense, AMAS, Central...). It is a single character as 'a' for AMAS star, 'd' for Defense star or 'c' for Central star ;
- 32-bits float value corresponding to the position of the star on X axis ;
- 32-bits float value corresponding to the position of the star on Y axis.

Note that the positions on the X axis and Y axis are relative to the card dimension. If the card is 512x512 pixels, the absolute position of the star will be got by (X * 512) and (Y * 512).

Links description

Similar to the Stars description. You first have the amount of links, called L.
On L iterations, you will find :
- One byte for the starting Star index ;
- One byte for the ending Star index.

An example of CARD file is attached to this page.