Centred# Tile Loading and Display Overview and Godot

CentrED# is a client/server map editor for Ultima Online, and it handles tile loading by reading the game’s MUL files (the same files used by the UO client/server). The goal is to replicate this logic both as a Godot Editor plugin (for design-time map editing) and at runtime (for an in-game tile viewer). In Centred#, the server typically reads the UO data files (maps, statics, art, etc.) and sends the relevant data to the client for display. The client either uses its own copy of the art files or receives art data from the server. To implement similar functionality in Godot, you’ll need to parse the .mul files the same way Centred# does and then create Godot Textures or Images to display the tiles. Below we identify the key parts of Centred#’s logic and how you can implement them. The following are notes and accuracy is not guaranteed. If anything may be erroneous, please provide an FYI.

Parsing Static Tile Data from MUL Files (Map Statics)

Static tiles in UO refer to world objects that are fixed on the map (buildings, trees, decor, etc.), stored in the statics files. Centred# reads these from the staticsX.mul files (with staidxX.mul as an index) for each map. The relevant code in Centred# is in its file-parsing routines (likely in the server component or a shared library) that handle reading static objects for each 8×8 map block. The process is roughly as follows:

• Open the index (staidx) and statics files: For a given map (e.g. map0), Centred# opens staidx0.mul and statics0.mul. The staidx file is an array of 12-byte entries, one for each map block (where the map is divided into 8×8-tile blocks). Each entry has: a 32-bit offset into the statics file, a 32-bit length, and a 32-bit unknown value. The number of entries corresponds to the number of blocks (e.g. 768×512 blocks for Felucca map0).
• Find the block’s statics data: To get statics at block (Xblock, Yblock), Centred# computes the index = Xblock * numBlocksY + Yblock. It reads the 12-byte index entry. If the offset is 0xFFFFFFFF, that means no statics in that block. Otherwise, the entry gives the file offset and length of the static data for that block.
• Read static objects: Centred# then seeks to that offset in statics.mul and reads the specified length of data. The statics data is a sequence of 7-byte records. Each static record has: a 2-byte ID (the tile graphic ID of the object, which corresponds to an entry in the art/tiledata files), a 1-byte X offset within the block (0–7), a 1-byte Y offset within the block, a 1-byte Z altitude (signed altitude relative to sea level), and a 2-byte “unknown” field. (In many implementations this unknown field is used as a hue or simply padding – UO’s client and server don’t document it well, but it’s often 0 unless a hue is applied).
• Example: If Centred# is loading block 1234, it reads the staidx entry at index 1234 to get (offset, length). Suppose length is 21, then there are three static objects (3 * 7 bytes) in that block. It would read three records from the statics file giving the IDs and positions of those objects. These IDs correspond to item art (in the art.mul file) and tile metadata (tiledata.mul). Centred# uses this to know which graphics to draw on that map section.
• Using the data: Once it has the list of static objects for the block, Centred# will load their art (see next section) and render them at the appropriate positions on top of the base terrain. The Centred# source likely contains a method that aggregates static tiles per map chunk. (In original CentrED, there was a Map class that loaded both terrain and statics for a requested area). The key point is that the Centred# code is reading those 7-byte static entries and storing them in a data structure (e.g. a list of static tile instances with id and position). You will need to replicate this logic in Godot – for example, by reading the binary files with Godot’s File API or C# System.IO, and extracting these records. This will give you the IDs of static tiles and their coordinates.

References: The format of staidx and statics files is documented (each index entry is 12 bytes, each static object 7 bytes). Centred# follows this format when parsing the files. The static loading code in Centred# will correspond to this structure – for instance, reading the index into a struct with fields for offset/length, seeking in the file, then looping to read each 7-byte static entry.

Loading Tile Art Images from ART.MUL

To display the tiles (whether individual tile graphics in a palette or the composed map), Centred# also loads the actual artwork from the UO art files. Ultima Online stores all terrain and object art in art.mul (with artidx.mul as an index). Centred#’s display logic for tiles would involve reading these files and converting them into bitmaps/textures for rendering on the screen. The code for this is likely in the Centred# client (or shared library) – possibly derived from the Ultima SDK or similar (many UO tools use a common approach). Here’s how it works:

• Art index lookup: The artidx.mul file contains an index of 12-byte entries (similar structure to other idx files): each entry has a 32-bit offset, 32-bit length, and 32-bit extra (often unused). To load a particular tile graphic, you multiply the tile ID by 12 to find its index entry, then seek to that offset in art.mul. (If the offset is 0xFFFFFFFF, the tile is not present). Land tiles (terrain) and static item tiles share the same art files but have different ID ranges. In UO: IDs 0–0x3FFF are land tiles, and IDs 0x4000 and above are static objects. In fact, in many tools the static object ID is handled by adding 0x4000 – e.g. an item ID 5 corresponds to artidx entry 0x4005. Centred# likely handles this by offsetting static IDs by 0x4000 when looking up art.
• Raw vs Run-length tiles: The art file uses two encoding formats. Centred# checks the first 4 bytes at the art.mul offset (often called a “flag” or header). In UO’s format:
  • If this 32-bit value is greater than 0xFFFF (or zero), it indicates a raw tile (terrain tile). Raw land tiles are a fixed 44×44 pixel image encoded in a specific way. No explicit width/height is stored (it’s implicitly 44×44), and the pixel data follows as 22 rows of increasing length then 22 of decreasing length (forming the diamond shape of terrain).
  • Otherwise (flag ≤ 0xFFFF and not zero), it’s a run-length encoded (RLE) tile – this is the format used for static object art, which have variable dimensions. In this case, the next 4 bytes (two 16-bit values) give the Width and Height of the bitmap. Then there is a lookup table of Height number of 16-bit offsets, which point to the start of each row’s data relative to a base position. After the lookup table, the actual pixel runs follow.
• Decoding static tile images: Centred#’s code will decode the RLE format to reconstruct the image. Pseudocode for this (based on Ultima SDK’s approach) looks like:
  1. Read Width (W) and Height (H) from the art data stream.
  2. Allocate a bitmap of size W×H (16-bit pixel depth, since UO art is 16-bit color 0xABGR format).
  3. Read H 16-bit values into an array LineStart[0..H-1], which are offsets to each scanline’s data (relative to the data section).
  4. For each row y from 0 to H-1: seek to the data start + LineStart[y]*2 (each offset is in words) and then decode runs:
     • Loop until you encounter a zero run-length indicator. Each run is encoded as two 16-bit values: XOffset and RunLength. The decoder will skip XOffset pixels from the left (move that many pixels into the line) and then copy RunLength consecutive pixel values from the stream to the bitmap.
     • This loop ends when a pair (XOffset, RunLength) equals 0 (i.e., XOffset + RunLength == 0, marking end of line).
     • Each pixel value is a 16-bit color. In UO’s format, the high bit of each pixel denotes transparency (1 = opaque). The decoder typically sets this high bit on all copied pixels to mark them as present. For example, the Ultima SDK code does pixelValue ^ 0x8000 to flip the transparency bit before storing (ensuring the pixel is opaque in the output image).
  5. Repeat for all rows, then unlock the bitmap. You now have the full image of the static tile.
• Decoding land tile images: For land tiles (44×44), the format is simpler (no explicit width/height stored since it’s always 44). The data is essentially 22 rows of increasing length (2,4,6,…,44 pixels) then 22 rows of decreasing length. Centred# likely uses a fixed routine for this. For example, a decoding loop might start at the top tip of the diamond and work downwards: beginning with an offset of 21 blanks and a run of 2 pixels, then 20 blanks and 4 pixels, etc., until the middle row of 44 pixels, then mirror the pattern. In code, one can initialize xRun = 2 and xOffset = 21 and then adjust those as you iterate over 44 lines to place pixels appropriately in a 44×44 bitmap. (The Centred# source likely has a LoadLand function very similar to this, which fills a 44×44 Bitmap with the land tile’s pixels).
• Caching and usage: In Centred#, once a tile image (land or static) is decoded into a Bitmap/texture, it might be cached for reuse. For example, if you open a tile picker UI, it will load the images on demand and keep them. The source code might have an array or dictionary of loaded tile Bitmaps. The Ultima SDK’s Art class, for instance, uses a cache array indexed by tile ID. In Godot, you could similarly cache ImageTextures for each tile to avoid re-decoding repeatedly.

References: The logic described above is corroborated by known UO format documentation and existing tools. The Heptazane format docs show how ART.MUL is structured and how to interpret raw vs run-length tiles. The Ultima SDK (used in programs like UOFiddler) implements this decoding in C#: for instance, it reads the width/height and then loops through run-length encoded segments to build the image. Centred#’s code will be doing the same thing – reading the artidx entry, then either calling a routine to decode a static tile or a land tile depending on the flag. By following that approach, you can implement your Godot plugin to load any UO art asset (including custom ones from ServUO/ClassicUO) and display them.

Implementing in Godot (Editor Plugin & Runtime Viewer)

For visual display in Godot, start with purely viewing tiles, then add interaction. Initially, you can create a Godot EditorPlugin that opens the UO files and displays a grid or list of tile images (similar to Centred#’s tile selector). Later, you can make those images selectable and use that selection to paint tiles onto a map.

Key implementation steps:

• Reading files: Use Godot’s file APIs or C# System.IO to open the .mul and .idx files. (In a GDScript tool script, you might use File.open() in binary mode. In C#, use FileStream or BinaryReader.) Read bytes according to the formats above. For example, to get a static tile image:
  1. Read the artidx entry for ID+0x4000 (for static item IDs) to get offset & length.
  2. Seek to offset in art.mul, read the flag (4 bytes) and decide raw vs run. Then decode as described (the decoding can be done in GDScript, though C# or C++ might be faster for large images).
  3. Convert the decoded 16-bit pixel data to a Godot Image. Godot Image supports 16-bit color, but it might be easier to convert to 32-bit (x2 the data) for a standard ARGB8888 Image. You’ll have to map the 0x7FFF/0x8000 format to Godot’s color; basically, each 16-bit pixel is 0xA B G R (1-bit alpha + 5-bit blue/green/red). In the decoded data, if you set the high bit for opaque pixels, then 0x8000 indicates a fully opaque black pixel (if color bits were 0). Typically, you can treat the 0x8000 bit as alpha: on output, set alpha=1 for any pixel where (pixel & 0x8000)!=0, and RGB = the lower 15 bits converted to 24-bit color.
  4. Create an ImageTexture from the Image and use it in a Sprite or UI TextureRect to display.
• Displaying maps: To render a map in Godot (runtime viewer), you’d combine 8×8 blocks. You would read map#.mul for terrain tiles (each block is 64 cells of 3 bytes: tile ID and altitude) and the statics as above. Then for each cell, draw the land tile image, and for each static in that cell, draw the static’s image (in the correct draw order – usually by altitude). This is similar to what Centred# client does when showing the map. A simple approach in Godot is to use a TileMap or manually draw sprites at the correct positions.
• Interaction: Once the visuals are working, you can add clicking. For example, in the Godot Editor plugin, you could make each tile image clickable to select that tile for painting. In the runtime map, you could allow clicking a spot to inspect which static tile is there, etc. These interactions are beyond Centred#’s core loading logic but integrating them in Godot is straightforward once the data is loaded (just use Godot’s input events on the sprites or an overlay).

Designing a ServUO/ClassicUO-Compatible .kul Format

You mentioned creating a .kul file format compatible with ServUO/ClassicUO. This suggests you want to package the tiles (and possibly maps) in a new way, but still have the game server and client recognize them. ServUO (the server) and ClassicUO (the client) currently expect the standard MUL/UOP files, so introducing .kul means you’d likely have to modify those programs to support it. Here are some considerations:

• Format choice: Decide if .kul is simply a repackaging of existing files or a new container. For example, you might combine mapX.mul, staidxX.mul, and staticsX.mul into one file for convenience (since those three always go together). Or you might create a custom art container. If you want ClassicUO to read .kul, you could implement it similarly to how it reads UOP or MUL: i.e., add a loader that recognizes the .kul extension and parses it. One idea is to use a UOP-like format (Ultima Online’s newer “Unity Optimized Package” format) but with your own extension, since ClassicUO already has code to handle UOP (it might be adaptable).
• ServUO compatibility: ServUO (being a RunUO derivative in C#) has file reading code for maps and statics. To use .kul there, you would either need to convert the .kul back into the expected .mul files at runtime, or modify ServUO’s map loading code to handle .kul. If .kul is just a renamed .mul or a concatenation, you could adjust the code accordingly. The easiest path is often to not stray far from the existing formats. For instance, if .kul combined map and statics into one, you could have a header that identifies sections (like one section for map data, one for static index, one for static data).
• ClassicUO client: ClassicUO’s code can be modified to support new file formats. You’d add a handler in its FileManager or resource loading section. Ensuring it’s “compatible” means ClassicUO could load either standard muls or your .kul. You might use a config or a naming convention (e.g., if a map0.kul exists, load that instead of map0.mul).
• Godot usage: If you have a custom .kul, your Godot plugin can be the tool that creates this file (perhaps exporting a custom map/art combination) and you’d also teach Godot to read it. Essentially, you become the author of the format, so you define how the data is stored. Keep in mind the structure from the mul files – for compatibility, it might literally contain the same bytes as mul files but in one archive. For example, .kul could start with a directory listing: e.g., offsets for sub-files (like the entire map mul chunk, statics index chunk, statics chunk, etc). This is similar to UOP which has a file index at the start.

In summary, Centred#’s source code for loading tiles involves two main parts: reading the placement data of statics (from staidx/statics) and reading the art pixel data (from art.mul via artidx). These are the parts you’ll want to replicate. Specifically, look at how Centred# parses staidx#.mul and statics#.mul to get static objects, and how it decodes the art for those objects from art.mul – likely using a routine equivalent to the Ultima SDK’s (reading width/height and run-length pixel data). Using that knowledge, you can implement a Godot plugin that loads the UO assets and displays them. For the .kul format, you will design a new container and update ServUO/ClassicUO to support it, ensuring it still stores the necessary data (tile IDs, maps, etc.) in a way those programs can utilize with minimal changes.

Sources:

• UO Stratics File Format documentation – explains the structure of STAIDX0.MUL (static tile index) and STATICS0.MUL (static objects), as well as ART.MUL encoding for land vs static tiles.
• Ultima SDK (UOFiddler/Razor) – example code for decoding art.mul images. The static tile run-length decoding loop shows how Centred# would reconstruct item art bitmaps (each run defined by X offset and length of pixels), and land tiles are handled as 44×44 fixed images.