Extracted Data File Types - HoraceAndTheSpider/Bloodwych-68k GitHub Wiki

Extracted data folders and file types

The files produced from segments.xlsx are byte-for-byte extracts from a supported game binary. Most do not contain a header, filename, dimensions, or other self-description. Their folder and faux-extension therefore describe how Bloodwych ReSource interprets the bytes.

The faux-extension is documentation rather than a new file format: renaming a file does not change its contents.

Folders

Folder	Purpose
`data/`	General game tables which are not graphical resources, maps, or sound.
`gfx/`	General graphics and their companion tables: walls, floor and ceiling artwork, interface pieces, doors, objects, avatars, and similar resources.
`gfx-data/`	Shared graphics-renderer and viewport tables used by several resource types. These are primarily extracted for decoding, validation, and documentation and are not normally presented as editable artwork.
`monsters/`	Graphics and companion data belonging to a particular large monster: graphic blocks, component layout, picture offsets, colour grades, and palettes.
`maps/`	Tower maps and their switches, triggers, objects, monsters, entrances, and related data.
`sfx/`	Sound data.

segments.xlsx uses the Type value as the folder name and DATA BLOCK FILE as the filename. The resulting name is normally Type/DATA BLOCK FILE.

Graphics-related faux-extensions

Extension	Meaning	Normal treatment in the Super App
`.gfx`	Raw Atari ST four-plane graphical data as stored by the game. It contains no dimensions or picture directory of its own.	Editable through graphical export/import tools.
`.offsets`	Big-endian word offsets locating individual pictures inside an associated `.gfx` block. This is the table that divides or selects pictures in sequential graphic data.	Generated and validated when graphics are imported; not normally hand-edited.
`.positions`	Signed screen X positions, Y positions, or packed X/Y pairs used when drawing a picture or component.	Advanced editable layout data with a live preview.
`.heights`	Stored picture heights used by the strip renderer. In several routines zero represents one drawn line because the value is used as a loop count.	Normally generated or validated against imported artwork.
`.layout`	A packed, resource-specific mixture of component dimensions, positions, graphic bases, spacing, or mirroring rules which cannot be separated cleanly without changing the original layout. This replaces the ambiguous `.renderdata` name.	Parsed into named fields and exposed through an advanced component-layout editor.
`.lookup`	A value-remapping table, such as view distance to graphic size or facing direction to a graphic variant. Unlike `.offsets`, its values are not necessarily byte positions in a `.gfx` file.	Usually fixed when shared by the renderer; monster-specific lookups may be regenerated with artwork.
`.flags`	Bit or word values which enable rendering behaviour such as animation or mirroring.	Normally fixed or expert-only.
`.colours`	A monster's ordered selections from the master monster palette, used for colour grades.	Editable with palette-index validation.
`.palette`	Palette entries or groups of palette indices.	Editable with format and range validation.

Other common faux-extensions

Extension	Meaning
`.font`	Raw game-font data.
`.sound`	Extracted sound sample data.
`.block`	A fixed-size binary structure which has not yet been given a narrower file type.
`.locations`	Encoded map or game locations.
`.map`	One tower's packed map data.
`.switches`, `.triggers`, `.obj`, `.monsters`	The corresponding fixed-capacity tower data block.

Editability is not encoded in the filename

All extracted files are ordinary binary files and can technically be changed. The Super App decides which files receive an editor and which are treated as read-only engine data. Shared renderer tables are kept in gfx-data/; monster-specific companion data is kept beside its .gfx file in monsters/.

The spreadsheet's extract_only action has a different meaning: it allows a useful sub-block to be extracted without replacing that exact source span with an INCBIN. It does not by itself mean that the data is editable or read-only.

Contiguous source layouts

Some adjacent source tables form one logical replacement even though they are extracted into several named files. The first spreadsheet row uses data_start; immediately following components use data_append. Their offsets and sizes must be exactly contiguous.

Column A on a data_append row may either repeat the data_start anchor (the original convention) or contain the real internal source label where that component begins. Using the internal label is preferable when it exists: the same row then both relabels the original source and emits the component in the generated data source. A separate duplicate relabel row is not required.

Labels before and after INCBIN generation

When a data_append row repeats the group anchor, its new component label does not exist in the original disassembly. This matters when code has already been rewritten to reference that component by name: the relabelled source must still compile before Inspect replaces the data with several labelled INCBIN resources.

ReSource therefore derives a temporary EQU from the component offsets. For example, the dungeon view tables use:

Dungeon_ViewCell_OcclusionMasks:
        equ Dungeon_ViewCell_RelativeCoordinates+$98

Dungeon_ViewCell_VisibleFaceMasks:
        equ Dungeon_ViewCell_RelativeCoordinates+$E4

These aliases produce the same addresses as the unsplit source block. When the whole grouped replacement validates, Inspect removes the temporary aliases and the generated INCBIN layout defines real labels at those boundaries. If validation fails, the aliases remain with the original data so the retained source still compiles.

The alias values are calculated from the existing offset fields; they are not additional spreadsheet data and must not be entered as _delete rows.

Odd-length resources and Devpac

Devpac forces every INCBIN to an even boundary and appends a zero byte when the included file has an odd length. This changes the executable if an odd-sized source table is replaced directly by INCBIN.

The ReSource inspector therefore emits:

even-sized external resources as INCBIN;
odd-sized external resources as generated dc.b lines containing the exact file bytes.

The extracted file remains authoritative in both cases. Rerunning Inspect / Data regenerates the assembly after the file is edited. This was confirmed with Monster_SubPosition_DepthAdjustments.positions (five bytes) and Monster_ViewCell_DepthSlots.lookup (19 bytes): using two direct INCBIN statements inserted two unwanted zero bytes, whereas generated dc.b data produced a byte-identical SPS 439 executable.