SWOS ITA Mod Technical Manual

Foreword

1Overview

The mod never touches the original files. A Python script reads orig/ITALIAN.EXE and orig/DATA/TEAM.020, applies every change deterministically and writes the installed files to c/SWOS/. Every address it needs is located in the executable by signature (unique byte sequences) and checked with assert: if a signature is missing or not unique, the build stops instead of producing a wrong exe.

2Environment and build

Folders

~/swos-mod/
  orig/            ITALIAN.EXE, ENGLISH.EXE, DATA/TEAM.020, swos9697ita.iso   (NEVER modify)
  c/SWOS/          game installed for DOSBox-X: ITALIAN.EXE, DATA/TEAM.020, *.CAR saves
  tools/           all the mod's code (Python + nasm sources inside sacups.py)
  ref/swos.asm     full IDA disassembly (labels = ENGLISH exe VAs), from github.com/zlatkok/swos-port
  ref/symbols.txt, ref/docs/SWOS/*.txt   file formats and notes (teams.txt, career.txt, ...)
  notes/STATUS.md  detailed log of every session (primary source)
  notes/addrmap.json  ENGLISH → ITALIAN delta map per object
  docs/            this manual (src/ = sources in both languages, tools/mkdocs.py builds the pages)

Commands

cd ~/swos-mod/tools && python3 patch.py      # writes c/SWOS/ITALIAN.EXE and c/SWOS/DATA/TEAM.020
python3 tools/salists.py c/SWOS/SAVE.CAR      # decodes a save's SA lists / Intercontinental pair
ndisasm -b32 -o 0xA1000 file.bin              # disassembler (Homebrew); nasm to assemble

Requirements: Python 3, nasm and ndisasm on the PATH. The game runs in DOSBox-X with the CD mounted from the original ISO. The build is deterministic: same inputs, same md5 (the random generator has a fixed seed, 1997).

Build order in patch.py:

1. patch_teams: rebuilds TEAM.020 (original Serie A and B + 36 C1/C2 clubs) and returns the index remap table.
2. patch_exe: adds a 4 KB page to object 1 (add_object_page), sets up the string pool, remaps Italian clubs in the European cup lists, applies the Italy patch (patch_italy), then all of sacups.patch (cups, tables, career, season end), sets object 1's vsize and flags, saves while rebuilding the fixup tables.

3Golden rules

Each of these rules comes from a real bug met during development.

4LE format and fixups

Each language executable (ENGLISH.EXE, ITALIAN.EXE, FRENCH.EXE, GERMAN.EXE) is a DOS/4GW program in LE (Linear Executable) format with two main objects. Values below are for ENGLISH.EXE:

Addresses in the disassembly (cseg_8B2D3, dseg_D8CAA) are ENGLISH.EXE virtual addresses: object offset = VA − base. The other languages are shifted by small deltas (notes/addrmap.json maps ENGLISH → ITALIAN); the build never relies on them and finds every location by signature.

Fixups

Every absolute address in the file has an internal fixup record (source object, offset in page, target object, target offset). When an instruction holding an address is overwritten, its fixup must be removed (p.remove), or the loader corrupts the new bytes. When an address is added, the fixup must be added (p.add_ptr). lepatch.save rebuilds the fixup table; if it grows past the available room it moves the data pages forward (0x800 bytes so far) and updates the header offsets.

Added page

add_object_page(data, 1) appends a 4 KB physical page at the end of the file, inserts it into the page map right after object 1's pages, adds an empty entry to the fixup page table, shifts the header table offsets by +4/+8 and increments object 2's page_idx. All South American cup code and data live in this page, from obj1+0xA1000. Today it is used up to about obj1+0xA1932 (about 1.7 KB free). The rest of the old cave after the Italy league structure, 0xA0BC6–0xA1000 (about 1 KB), is still free.

5The tools

le.py

Read-only LE parser: objects, page → file map, obj_bytes(n), fixups() returning (source obj, offset, type, target obj, target offset, …). Used for all checks.

lepatch.py

LEPatch class: put/get by object and offset, target(obj, off) reads where a fixup points, add_ptr, remove, retarget, set_vsize, add_flags, save (fixup rebuild + data page move). add_object_page function. A round trip with no changes gives an identical file.

nasmcave.py

Assembles nasm sources (written as strings inside sacups.py) at a cave address. Symbols come as {name: (object, offset)}. The source is assembled three times: plain, with obj1 moved by 0x01000000 and with obj2 moved. Every dword that changes is an absolute reference and gets a fixup to the right object; relative jumps inside obj1 do not change and need none. labels() reads nasm's map file for label addresses.

strpool.py

Room for new strings in object 2: the never-referenced strings .COPPA AFRICANA CLUB****** and COPPA SUDAMERICANA*****, plus the asterisk padding of the second COPPA EUFA and of ERRORE DISCO (the text stays intact). Holds COPA LIBERTADORES, SUPERCOPA, COPA CONMEBOL, SERIE C1, SERIE C2 and a shortened name for COPPA INTERCONTINENTALE. Full: 1 byte left.

sacups.py

The heart of the mod: South American cup and Intercontinental structures, continental tables, nasm sources CAREER_ASM (season start and load) and QUALIFY_ASM (season end), all signature searches and hook installation.

patch.py

Build entry point: Italy (global number base, 4-division structure), TEAM.020, remap of Italian clubs in the European cups.

c1c2.py / c1c2_rosters.py

C1/C2 clubs (kits, division), real 1996-97 squads with coaches, strength targets, team record construction (section 8).

salists.py

Reads a .CAR and prints the saved block: format (SA or S2), checksum, Libertadores/Supercopa/CONMEBOL lists, Intercontinental pair.

addrmap.py

Builds notes/addrmap.json by comparing ENGLISH.EXE and ITALIAN.EXE in masked windows (fixup bytes excluded).

asmbytes.py

Extracts the db bytes of a data label from ref/swos.asm, handy to find the same tables in the other language executables.

mkdocs.py

Builds docs/index.html (English) and docs/it.html (Italian) for GitHub Pages from the sources in docs/src/.

6Memory map (ENGLISH.EXE)

Offsets relative to the object, in ENGLISH.EXE. In this executable every offset is exactly the disassembly address minus the object base (obj1 0x10000, obj2 0xC0000): dseg_D8CAA is obj2+0x18CAA. ITALIAN, FRENCH and GERMAN have the same layout at other offsets; the build finds all of them by signature (the Italian values are in the Italian manual).

Object 2: data

Object 1: code (game routines used by the mod)

7Italy with 4 divisions

The 1997 season-end freeze

Every team has a global number (0–1999) used as an index into someLeaguesTable. Italy started at 424 with only 51 numbers: adding teams overflowed into Latvia (475). The extra teams collided, and at season end the cseg_91428 assert (80 teams in the European lists, counters 16/32/32) ended in int 3; jmp $. In 1997 the original mod inserted bytes between Italy's structure and Latvia's: about 50 league structures reached through fixed pointers were read out of alignment and the game froze.

The fix: Italy's base moves to 1850 (numbers 1794–1999 are free) in the teamsCountryNumbers table, and the new league structure goes into the obj1 cave, with the italyTable fixup retargeted (and widened from 16 to 32 bits).

League structure

10-byte header: [num, type, country, start, end, nameOff, 0, 0, 0, nDiv]
02 03 35
6 bytes per division: [teams, direct promotions, promotion play-off teams, relegated, relegation play-off, play-off data offset]
00
2 dwords per division: name offsets (from STR_BASE)

The mod uses DIVISIONS in patch.py: A (18, 0, 0, 4), B (20, 4, 0, 4), C1 (18, 4, 0, 4), C2 (18, 4, 0, 0). England already has 4 divisions in the same format: the engine handles 4 levels with no code changes.

8C1/C2 teams and squads

TEAM.020

The file starts with a big-endian word (team count) followed by 684-byte records. In the record: +1 ordinal, +2 global number (big-endian), +5 name (17 B), +25 division (0 A, 1 B, 2 C1, 3 C2; 4 was "non-league"), +26 first kit (5 B), +31 second kit, +36 coach (23 B), +60 order of the 16 players in the line-up, +76 16 players of 38 bytes.

The final file has 74 teams (A 18, B 20, C1 18, C2 18), sorted alphabetically, and stays under the limit of about 93 teams per nation (teamFileBuffer, 64014 B). Since the order differs from the original, remap_italian_cup_teams fixes the indexes of Italian clubs in the European cup lists (by name).

How a club is built (c1c2.real_team)

1. Real squad from the it.wikipedia page "<club> 1996-1997" (squad section), split into P/D/C/A. Known regulars come first; the rest follow the page order.
2. A template is chosen among the 13 original non-league clubs with a compatible role mix (G/D/M/A counted over the 16 positions), at random among the best fits.
3. Each template position gets the next name of the matching role; if the role runs out, a neighbouring role lends one. For clubs that already existed, a missing role (for example the second goalkeeper) is filled with an original SWOS player of that club.
4. The template's skills and prices move by whole steps towards an average price target taken from the real standings (1 skill step = 2 price units, clamp −3…+2). C1: 15.5–19; C2: 12–15; the original Serie B averages 17.9.
5. Names already in the file (mid-season transfers) go last in their role list, to avoid duplicates. Names over 22 characters: first-name initial (M. DAL COMPARE).

9Contest structure

[0]  contest id          [1] type: 1 knockout, 2 groups + knockout
[2]  nation (FF = any)
[3],[4] months: 8 × month counted from January of the season's first year (≥ 12 = next year)
[5]  names at +5+[5]: two dwords, offsets from STR_BASE (strings in object 2!)
[7]  team list at +7+[7]: byte pairs (TEAM file number, index)
[8]  1 = fixed list
type 1: [10] team count, [14..] one byte per round (0x94 two legs, 0x14 single-match final), then 00
type 2: [15] team count, groups of 4

Free ids: 0x70–0x7B (leagues use 0x24–0x6B, 0x7C custom, 0x7D–0xB1 cups). South American teams come from TEAM.043 (ARG), 045 (BOL), 046 (BRA), 048 (CHI), 049 (COL), 050 (ECU), 064 (PAR), 065 (PER), 071 (URU), 077 (VEN).

10Continental tables and world view

ViewWorldMenu → ChooseCompetitionMenu → SelectTeamsFinalMenu: every pointer in the continent's competitionsTable entry becomes a button. The European cups get no special treatment, so adding pointers is enough.

When a competition is picked, cseg_3AA17 checks whether it is one of the player's 4 slots (real state). Otherwise cseg_3ABB2 regenerates it on the fly: random seed = contest id << 8 | season, then it simulates up to the current date. Competitions the player is not in have no persistent state: to show them, a structure and a team list are all that is needed.

• South America table moved from obj2+0x8FD8 to obj1+0xA10E4: World Cup qualifiers, Copa América, Libertadores, Supercopa, CONMEBOL, Intercontinental.
• Europe table also moved to obj1: 252, Champions Cup, Cup Winners' Cup, UEFA, Intercontinental, −1, 43 nations. Five green buttons fit.
• International list (dseg_C707E, obj2+0x707E) moved to obj1+0xA1154 with the 4 added cups: for these contests the DIY field 0x3B is 0 (simulation, CalculateViewResult).

11Career: the 5 slots

In career mode every team has 5 competition slots. For each slot the game keeps a contest pointer (dseg_D8CAA + 4 × slot, 0 = empty) and a 0x443-byte buffer with the running competition. The calendar walks the slots and plays the week's matches.

Buffer header

+0 type (word), +27h name pointer, +2Bh slot number (word), +2Dh contest id, +3Dh/+3Fh/+41h substitution rules (5 on the bench, 2 changes, 8).

cseg_8B2D3 (load a contest into a slot)

• Writes the pointer into D8CAA[slot] and +2Bh = slot, then checks the type: slots 1 and 2 accept only type-1 (knockout) cups, slot 4 only type 1, slot 0 no type 1. A wrong type leads to int 3.
• Slot ≠ 4: takes the teams from the contest's list (D2 = 0) or from the selected teams (D2 ≠ 0), builds the draw and schedules the dates (cseg_8B71C + cseg_8B8B8).
• Slot 4: fills the list with careerTeam repeated (placeholders) and does not schedule. At the league's end cseg_8ECAE reads from D8CC0 which standings positions go to the play-offs, replaces the placeholders (cseg_32E15), schedules, copies the league's substitution rules and sets D6B62 = 1 ("you cannot be sacked during the play-offs").

12Season start

ContinueCareerNextSeason (and InitCareer) call InitializeNewSeason: slots 0, 1, 2 from the nation's table, then the European cup chain (cseg_8D661 with D7 = 0, 1, 2 on Champions Cup, Cup Winners' Cup, UEFA), finally call cseg_8DAC3 (slot 4, play-offs).

flowchart TD
  A[InitializeNewSeason: slots 0, 1, 2] --> B{Club in a European cup?}
  B -- yes --> F[euro_found: int_step, then E092F = D7]
  B -- no --> I[init_sa]
  I --> I1{Saved block 'S2' or 'SA'?}
  I1 -- no, new career --> I2[DEFAULTS into lists + INTLIST, lists_out]
  I1 -- yes --> I3
  I2 --> I3{Slot 1 empty and club in the Supercopa?}
  I3 -- yes --> I4[Supercopa into slot 1]
  I3 -- no --> I5
  I4 --> I5[int_step: Intercontinental into slot 2 if free and club is a finalist]
  I5 --> I6[Slot 3: Libertadores, Supercopa unless already in slot 1, CONMEBOL; D8CBE = D7 - 3]
  F --> D[call cseg_8DAC3 redirected to int4_step]
  I6 --> D
  D --> D1[cseg_8DAC3: play-offs into slot 4 if the division has them]
  D1 --> D2{Slot 4 empty, club a finalist, Intercontinental not in slot 2?}
  D2 -- yes --> D3[Intercontinental into slot 4 via the buffer swap]
  D2 -- no --> Z[done]
  D3 --> Z

Intercontinental in slot 4: the buffer swap

Loading the cup straight into slot 4 would give a "your team against your team" match with no dates. int4_step instead:

1. calls the real cseg_8DAC3; if slot 4 is taken (play-offs) it stops;
2. clears buffer 4's id (so an old buffer is not restored on load);
3. copies the slot 2 buffer (league cup) into buffer 4;
4. calls cseg_8B2D3 with slot 2: the Intercontinental is built in full, with the finalists and the dates;
5. swaps the two 0x443-byte buffers: Intercontinental in slot 4, league cup back intact in slot 2;
6. +2Bh = 4, substitution rules from the league (as the game does for play-offs), restores the slot 2 pointer, D8CBA = INT.

The playoffs hook at the entry of cseg_8ECAE returns at once when slot 4 holds the Intercontinental: otherwise at the league's end the game would rebuild it from a play-off table that does not exist.

13Loading a save

ProcessCareerFile rebuilds the slot pointers from the nation's table (slots 0–2), the division record (slot 4) and E092F (slot 3). The slot buffers are in the save, the pointers are not: the mod restores them from the id stored in the buffers.

• load_slot1: reads the saved block (section 15) into the lists; if slot 1 is empty and buffer 1 has id 0x6D → Supercopa; if slot 2 is empty and buffer 2 has id 0x6F → Intercontinental; if slot 4 is empty and buffer 4 has id 0x6F → Intercontinental.
• load_slot3: extends the E092F mapping: 3 → Libertadores, 4 → Supercopa, 5 → CONMEBOL.

14Season end

cseg_91428: combines the lists; for the player's nation and then every European nation it simulates or reads the standings (cseg_9153F), promotions, cups; cseg_92D55 / 9307A / 9339D close the Champions Cup, Cup Winners' Cup and UEFA; cseg_93974 adds the qualifiers; final 80-team assert (16/32/32); cseg_92BBF re-admits the holders.

The mod redirects the call to cseg_92D55 (obj1+0x81470) to sa_qualify:

1. [A4] = Libertadores and call cseg_92D55 + 10 (skips the first instruction, which would select the Champions Cup): closes the Libertadores (played by the player or simulated with cseg_3ADAE) and writes the winner into dseg_18070F → LIBWIN.
2. For each South American nation: simulates the top division with cseg_915ED (the same simulation as the world view, so the standings match). For the player's own division it reads slot 0 instead. From the DIY: +6Dh row offsets in finishing order (rows of 12h bytes), +12Dh team number per row.
3. Writes the qualifiers: Libertadores = champions of the 10 countries + runners-up of ARG, BRA, URU, PAR, COL, CHI (4 mixed groups, LIB_Q); CONMEBOL = the next places (CON_Q, 8 pairs). Supercopa: fixed list of former champions.
4. Holder rules (real 1997): if LIBWIN is not already in the Libertadores it takes its country's runner-up place (else CHI2), and the displaced club takes its place in the CONMEBOL; if it is not in the Supercopa, it takes the last place.
5. The real call cseg_92D55: closes the Champions Cup. Both branches end in cseg_92F1C, which always writes the winner to dseg_18070F.
6. INTLIST[0] = [dseg_18070F], INTLIST[1] = LIBWIN (each skipped if 0FFFFh), then lists_out and ret.

flowchart LR
  S[cseg_91428 season end] --> Q[sa_qualify]
  Q --> L[Libertadores end: LIBWIN]
  L --> C[SA standings → Lib and CON lists]
  C --> H[Holder rules]
  H --> E[real cseg_92D55: CC winner]
  E --> N[INTLIST = CC, LIBWIN]
  N --> O[lists_out: saved block + checksum]
  O --> R[back to cseg_91428]

15Persistence in the save

The save holds someLeaguesTable (2000 bytes, one per global number). Numbers 1730–1849 belong to no team: the mod parks its data from number 1740 (obj2+0x18534), mirrored in leaguesTableCopy (obj2+0x59ABE), because at season end the game copies one table onto the other (cseg_8CC0A and cseg_8CC4E). InitCareer clears the table: an all-zero table means a new career.

The balance byte is −(sum of the block's preceding bytes) mod 256, so the whole block sums to 0 and the table stays at 0 for cseg_9487A's check. Reading: 'S2' everything from the save; 'SA' the three lists plus the default Juventus – River pair; no marker → 1997 values (DEFAULTS, 100 bytes). The first season end of an 'SA' career rewrites it as 'S2'.

# check in Python
blk = save[SAVED:SAVED + 103]
assert blk[:2] == b'S2' and sum(blk) % 256 == 0

16Trophies and reputation

Trophy bits are built in cseg_39392 from the flags D6C64 (Champions Cup, bit 2, reputation +100), D6C68 (UEFA, bit 3, +50) and D6C66 (Cup Winners' Cup, bit 4, +50). cseg_3D7CB picks the flag from dseg_D8CBE, cseg_5DEB9 the prize. The mod sets D8CBE = D7 − 3 when a South American cup is entered:

• Libertadores counts as the Champions Cup;
• Supercopa in slot 3 counts as the Cup Winners' Cup;
• CONMEBOL counts as the UEFA Cup;
• Supercopa in slot 1 counts as the national cup.

The season record (ManagementRecordMenu) already shows the right name ("COPA LIBERTADORES - WINNERS"). Dedicated names and bits (bits 10–15 are free) would need new strings, and the pool is full.

17Hook table

Each hook overwrites original instructions with a jmp or changes a call target; the fixups of the overwritten instructions are removed.

Data changes: Italy's base in the global number table; italyTable fixup retargeted to the new structure; South America, Europe and international list tables retargeted into obj1; new names in the string pool; indexes of Italian clubs in the European lists; object 1 vsize and flags.

18Verifying without playing

Before handing out a build for testing, these checks are run every time:

1. The build passes every assert (unique signatures, expected targets).
2. Re-read with le.py: the fixup tables parse without errors.
3. ndisasm of the generated code and of every hook site: every jump goes to the right label.
4. Every absolute operand has a fixup to the correct object and offset (the script annotates each disassembly line with its fixups).
5. Comparison with the previous build: bytes change only where intended; the only fixups changed outside the added page must be the expected ones.
6. For saved data: Python emulation of the checksum on a copy of a real save.

If a check fails and cannot be fixed, the previous build is put back (ITALIAN_S12.EXE is the last one tested in depth).

19Limits and open issues

• C1/C2 groups. In 1996-97 C1 had 2 groups and C2 had 3. The mod uses one group per series. The full reality (128 teams) does not fit the limit of about 93 teams per nation. C1 with two groups would fit (92), but it needs promotions and relegations between parallel divisions, and checks on the 80-team career limit and on global numbers: estimated 2–3 sessions.
• Intercontinental in slot 4. A finalist in a division with play-offs gets no Intercontinental. The routine cseg_8BF89 (called by cseg_8B2D3) has not been analysed: if it keeps data tied to the slot number, the buffer swap could leave it inconsistent. In the season record the Intercontinental in slot 4 has no name.
• Strings. The object 2 pool is full: new names need more room (other unused strings, or a data page added to object 2 with the same technique used for object 1).
• Dedicated trophies. South American cups use the trophies of the European cups of the same rank.
• Old saves. They cache the team data from when they were created: the new squads show only in a new career.
• Duplicates. 5 repeated names remain (mid-season transfers or namesakes). The original SWOS data had 61.
• English bench (after 1.0). In the pre-match line-up English clubs show 14 players (11 + 3 on the bench). The original game does the same, and TEAM.008 has 16 players per club: it is a game rule. To do: find where the bench size comes from (rules at buffer +3Dh…41h, values 5/2/8 set by InitCareer) and raise it to 5.

20History and next steps

Roadmap

1. Tests of sessions 12–14 and fixes.
2. Port to ENGLISH/FRENCH/GERMAN.EXE from the same CD. To be made generic: STR_BASE, the pseudo-register offsets written into sacups.py's regular expressions, the pool's source strings (Italian texts), displayed names, slot addresses (all found by signature: to be rechecked one by one).
3. Patcher as a single HTML/JS file that ships only differences: users pick their own original files, the patcher checks the md5s, applies the differences and downloads the patched files; README in Italian and English; to uninstall, keep the originals.
4. After 1.0: 5-man bench for English clubs; Intercontinental in slot 4 test; C1 with two groups, after an analysis-only session.

Credits: disassembly and file format documentation from swos-port (zlatkok). Mod: Davide Lorigliola, with Claude.