CipSoft SectorConverter

CipSoft SectorConverter is a tool developed to convert CipSoft .sec map files from binary format into plain-text format.

The code responsible for reading binary sector files and writing text output is adapted from the decompiled Tibia gameserver available at fusion32/tibia-game with minor modifications to use more modern C++ and simplify maintenance.

The script file reader is adapted from danilopucci/script-reader with small changes to keep everything in a single pair of .cpp/.h files and to improve logging.

---

Requirements

• C++20 compiler
  • Linux: GCC ≥ 13 or Clang with libc++
  • Windows: Visual Studio 2022 or newer
• CMake ≥ 3.16 (Linux)

---

Compiling on Windows

A Visual Studio solution is provided.

Simply open the solution file and build the project as usual.

---

Compiling on Linux (tested on Ubuntu 24.04)

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
cp build/sector_converter .

How to run

This program contains hardcoded paths, which can be adjusted at the very beginning of the main() function.

The expected directory structure is:

├── ./sector_converter (or SectorConverter.exe)
├── ./dat
│   ├── ./dat/conversion.lst
│   ├── ./dat/objects.srv
├── ./map.bak
│   └── ./map.bak/binarySectorFiles.sec

Running

• Windows:

  SectorConverter.exe
  

• Linux:

  ./sector_converter

---

Output

• Logs are printed to the console
• Additional .log files are created for:
  • info
  • warnings
  • errors
  • debug output

The program creates a new directory with the _converted suffix
(for example: map.bak_converted) containing the converted text sector files.

---

Binary .sec file layout (reverse-engineered)

The CipSoft .sec files are binary sector files representing a 32×32 tile map slice at a given floor (Z). This layout is reverse-engineered and implemented in BinarySectorLoader.

Filename encoding

Binary sector filenames encode their sector coordinates in hexadecimal:

XXXYYYZ.sec

• XXX → sector X (hex)
• YYY → sector Y (hex)
• Z → sector Z (hex, single digit)

Example:

3e73da8.sec -> 0999-0986-08.sec

---

High-level structure

[1 byte]  Sector header / flags
    - Its purpose currently unknown, but useless for the conversion 
    - this might be some optimization in order to skip the non-refreshable tiles at the game server
[1024 bytes] Tile flags block
    - 32 × 32, one byte per tile, row-major
    - the flags values are 0x00 -> none; 0x01 -> Refresh; 0x02 -> Nologout; 0x04 -> ProtectionZone
[variable] Tile content stream

---

Tile flags block

Immediately after the header byte, the file contains 1024 bytes:

• One flag byte per tile
• Tiles are stored in row-major order
• These flags are OR-ed directly into the tile structure

---

Tile content stream

After the tile flags block, the file contains a compressed tile content stream.

Control bytes:

• 0xFE → Skip tiles
  • Followed by 1 byte indicating how many tiles to skip
• 0xFF → Tile delimiter / end marker (used internally while parsing)

Tiles are processed sequentially from tile index 0 to 1023.

---

Tile content format

For each non-skipped tile, the content list is read:

[TypeID]
[Attribute 1] (uint32)
[Attribute 2] (uint32)
[Optional instance attributes...]

• TypeID is resolved via conversion.lst file
• The two base attributes are always present, but its value might be zeroed if the object do not have any instance attribute
• Additional instance attributes are conditionally read depending on the object definition in objects.srv

The presence and order of instance attributes is determined by object flags.

---

Instance attributes

• Instance attributes are parsed in reverse order
• Attributes are only read if the object declares them
• Text-based attributes (e.g. text strings) do not consume numeric attribute slots

---

This layout description reflects the logic implemented in:

• binarysectorloader.cpp
• readbinaryfile.cpp
• objects.cpp

Text sector file layout (generated format)

After conversion, each binary .sec file is written as a plain-text sector file. This format is designed to be human-readable, diff-friendly, and easy to inspect or post-process.

The text format preserves all relevant information from the binary sector while making tile contents and attributes explicit.

---

File purpose

Each text sector file represents:

• One 32×32 tile sector
• At a specific sector coordinate (X, Y, Z)
• Containing tile flags and a list of objects per tile

---

General structure

The file is written sequentially and consists of:

1. Sector metadata
2. Tile-by-tile data
3. Object and attribute listings

The exact formatting is stable and deterministic, making it suitable for version control and automated analysis.

---

Tile entries

Tiles are written only if they contain relevant data
(empty tiles are omitted).

Each tile entry includes:

• Tile coordinates (local to the sector: 00–31)
• Tile flags (if any)
• One or more tile contents (objects)

Disclaimer

This tool is intended for reverse-engineering and educational purposes.
All original file formats and assets belong to CipSoft GmbH.