AEPi 0.8.4

Read and write Abyss Engine Image (AEI) files from python, for Galaxy on Fire 2

AEPi

Abyss Engine Image (AEI) conversion for python
Join The Kaamo Club discord server for Galaxy on Fire fans and modding

Table of Contents

1. About The Project
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
• Open an .aei file on disk
• Create a new AEI
4. Roadmap
5. Contributing

About The Project

Abyss Engine is an internal-only game engine developed by Deep Silver FishLabs, for the development of the Galaxy on Fire game series.

The engine uses a proprietary file format for grids of images, called Abyss Engine Image (AEI). The image compression is platform dependant, for example Android texture files are compressed with Ericsson Texture Compression (ETC).

The AEI format was analysed by the Russian modding group 'CatLabs', who later created a GUI and command-line tool for conversion between PNG and AEI, named AEIEditor.

This tool was closed-source, and relied on a windows DLL for compression. AEPi is a minimal recreation of the image conversion logic provided by AEIEditor, leaning on open source image codecs:

• K0lb3/etcpak
• K0lb3/tex2img

See the project roadmap for currently supported and upcoming features.

Getting Started

Prerequisites

• python 3.11+ is required, as this project uses structural pattern matching.

Installation

install AEPi from PyPi:

python -m pip install aepi

Usage

This library reflects the real representation of an AEI file on disk; though textures are added to and read from an AEI object as individual images, the underlying representation is a single image. This improves encoding/decoding performance, and enables overlapping textures.

For maximum flexibility, AEPi returns AEIs as BytesIO objects.

The recommended best practise is to wrap your AEPi call in a with statement, to ensure that all of the AEI's images are cleaned out of memory when it goes out of scope.

Open an .aei file on disk

from AEPi import AEI

with AEI.read("path/to/file.aei") as aei:
  print(
    f"The AEI is compressed in {aei.format.name} format, "
    f"with {len(aei.textures)} textures. "
    f"Width: {aei.shape[0]} Height: {aei.shape[0]}"
)

Reading textures as image segments

AEI.textures provides read access to all of the AEI's bounding boxes. The AEI.getTexture method returns the relevant segment of the AEI, as a Pillow Image.

Using this, you could for example, batch export all of the individual images within an AEI:

for i, tex in enumerate(aei.textures):
  with aei.getTexture(tex) as im:
    im.save(f"batch/export/{i}.png")

Create a new AEI

from AEPi import AEI, CompressionFormat,
from PIL import Image

image_path = "ship-texture.png"
image2_path = "another-texture.png"

# create a new .aei file
with Image.open(image_path) as image, Image.open(image2_path) as image2:
  # Images are always assumed to be RGB(A). AEPi handles channel swapping for ETC1 to BGR(A)
  with AEI(image) as new_aei:
    # 'textures' - image bounding boxes
    new_aei.addTexture(image2, 0, 0)
    # The below operation is legal, but would leave unused image content in the AEI!
    new_aei.removeTexture(0, 0, image2.width, image2.height, clearImage=False)

Write a new AEI file to disk

    with open("path/to/newFile.aei", "wb") as new_file:
      # compression format can be specified at write time, or in the constructor
      aei.write(new_file, format=CompressionFormat.DXT5)

Roadmap

The AEPi 1.0 release will mark feature parity with AEIEditor, which theoretically reflects all of the capabilities required to manipulate Galaxy on Fire 2 AEIs on all platforms.

For details of the work that needs to be done, see the issues listed under the 1.0 milestone: https://github.com/Trimatix/AEPi/milestones

Other work is needed (e.g documentation, QOL improvements...), but below is an overview of the features implementation progress towards AEIEditor parity:

Feature	Read support	Write support
Raw image content	✅	✅
Basic metadata	✅	✅
Texture regions	✅	✅
Mipmapping	✅	❌
Compression quality (l/m/h)	❌	❌
Symbol maps	❌	❌

And compression format support progress:

Format	Read support	Write support
Uncompressed	❌	❌
Uncompressed_UI	✅	✅
Uncompressed_CubeMap_PC	✅	✅
Uncompressed_CubeMap	✅	✅
PVRTC12A	❌	❌
PVRTC14A	❌	❌
ATC	✅	❌
DXT1	✅	❌
DXT3	❌	❌
DXT5	✅	✅
ETC1	✅	✅

Extra feature requests for after the 1.0 release are very welcome.

To report a bug or request a feature, please submit an issue to the open issues page of this repository.

Contributing

This project has a huge amount of potential to help the community and extend the lifetime of our beloved game series. Your contributions will make that possible, and so I thank you deeply for your help with this project.

Please star the repository to let me know that my work is appreciated!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request