toto-script-tool 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,709 @@
1
+ """AdvHD WS2 script format handler.
2
+
3
+ WS2 files are bytecode scripts used by the AdvHD visual novel engine (Willplus/Will).
4
+ They contain single-byte opcodes with variable-length operands and UTF-16LE strings.
5
+ See doc/advhd-ws2.md for format documentation.
6
+ """
7
+
8
+ import logging
9
+ import re
10
+ import struct
11
+ from io import BytesIO
12
+
13
+ from ..util import TextLine
14
+ from .TranslatableFile import TranslatableFile
15
+
16
+ logger = logging.getLogger(__name__)
17
+
18
+ MAGIC = b'WS2I'
19
+
20
+ # Chunk types for intermediate format
21
+ _RAW = 0
22
+ _DIALOGUE = 1
23
+ _NAME = 2
24
+ _CHOICE = 3
25
+
26
+ # Matches %K, %P, or %K%P at the end of dialogue text
27
+ _EOL_RE = re.compile(r'(%K%P|%K|%P)$')
28
+
29
+ # ---------------------------------------------------------------------------
30
+ # Opcode signature table
31
+ #
32
+ # Maps opcode (int) -> list of operand type codes, terminated by -1.
33
+ # Types: 0=byte, 1/2=word(u16), 3/4=int/ptr(u32), 5=float, 6/9/10=string, 7=array, 8=marker(0 bytes)
34
+ # Source: Lite0812/AdvHD2.1_WS2_Toolkit disasm_ws2.py
35
+ # ---------------------------------------------------------------------------
36
+ _SIGS = {
37
+ 0x00: [-1],
38
+ 0x04: [10, 8, -1],
39
+ 0x05: [-1],
40
+ 0x07: [10, 8, -1],
41
+ 0x08: [0, -1],
42
+ 0x09: [0, 1, 5, -1],
43
+ 0x0A: [1, 5, -1],
44
+ 0x0B: [1, 0, -1],
45
+ 0x0C: [1, 0, 7, 1, -1],
46
+ 0x0D: [1, 1, 5, -1],
47
+ 0x0E: [1, 1, 0, -1],
48
+ 0x11: [6, 8, 0, 5, -1],
49
+ 0x12: [6, 8, 0, 10, 8, -1],
50
+ 0x13: [-1],
51
+ 0x14: [4, 6, 8, 6, 8, 0, -1], # DisplayMessage
52
+ 0x15: [6, 8, 0, -1], # SetDisplayName
53
+ 0x16: [0, 0, -1],
54
+ 0x17: [-1],
55
+ 0x18: [0, 6, 8, -1], # AddToLog
56
+ 0x19: [-1],
57
+ 0x1A: [6, 8, -1],
58
+ 0x1B: [0, -1],
59
+ 0x1C: [6, 8, 6, 8, 1, 0, -1],
60
+ 0x1D: [1, -1],
61
+ 0x1E: [6, 8, 10, 8, 5, 5, 1, 1, 0, 5, -1],
62
+ 0x1F: [6, 8, 5, -1],
63
+ 0x20: [6, 8, 5, 1, -1],
64
+ 0x21: [6, 8, 1, 1, 1, -1],
65
+ 0x22: [6, 8, 0, -1],
66
+ 0x28: [6, 8, 10, 8, 5, 5, 1, 1, 0, 1, 1, 0, 5, -1],
67
+ 0x29: [6, 8, 5, -1],
68
+ 0x2A: [6, 8, 5, 1, -1],
69
+ 0x2B: [6, 8, -1],
70
+ 0x2C: [6, 8, -1],
71
+ 0x2D: [6, 8, 0, -1],
72
+ 0x2E: [-1],
73
+ 0x2F: [6, 8, 1, 5, -1],
74
+ 0x30: [6, 8, 5, -1],
75
+ 0x32: [10, 8, -1],
76
+ 0x33: [6, 8, 10, 8, 0, 0, -1],
77
+ 0x34: [6, 8, 10, 8, 0, 0, -1],
78
+ 0x35: [6, 8, 10, 8, 0, 0, 0, -1],
79
+ 0x36: [6, 8, 5, 5, 5, 5, 5, 5, 5, 0, 0, -1],
80
+ 0x37: [6, 8, -1],
81
+ 0x38: [6, 8, 0, -1],
82
+ 0x39: [6, 8, 0, 0, 7, 1, -1],
83
+ 0x3A: [6, 8, 0, 0, -1],
84
+ 0x3B: [6, 8, 6, 8, 1, 1, 1, 5, 5, 5, 5, 5, 5, 5, 5, -1],
85
+ 0x3C: [6, 8, -1],
86
+ 0x3D: [1, -1],
87
+ 0x3E: [-1],
88
+ 0x3F: [7, 6, -1],
89
+ 0x40: [6, 8, 10, 8, 0, -1],
90
+ 0x41: [6, 8, 0, -1],
91
+ 0x42: [6, 8, 1, -1],
92
+ 0x43: [6, 8, -1],
93
+ 0x44: [6, 8, 6, 8, 0, -1],
94
+ 0x45: [6, 8, 1, 5, 5, 5, 5, -1],
95
+ 0x46: [6, 8, 1, 0, 5, 5, 5, 5, -1],
96
+ 0x47: [6, 8, 6, 8, 1, 0, 0, 5, 5, 5, 5, 5, 1, 5, -1],
97
+ 0x48: [6, 8, 6, 8, 1, 0, 0, 10, 8, -1],
98
+ 0x49: [6, 8, 6, 8, 10, 8, -1],
99
+ 0x4A: [6, 8, 6, 8, -1],
100
+ 0x4B: [6, 8, 1, 1, 5, 5, 5, 5, -1],
101
+ 0x4C: [6, 8, 1, 1, 0, 5, 5, 5, 5, -1],
102
+ 0x4D: [6, 8, 6, 8, 1, 1, 0, 0, 5, 5, 5, 5, 5, 1, 5, -1],
103
+ 0x4E: [6, 8, 6, 8, 1, 1, 0, 0, 10, 8, -1],
104
+ 0x4F: [6, 8, 6, 8, 1, 10, 8, -1],
105
+ 0x50: [6, 8, 6, 8, 1, -1],
106
+ 0x51: [6, 8, 6, 8, 1, 5, 0, -1],
107
+ 0x52: [6, 8, 6, 8, 5, 1, 5, 0, 10, 8, -1],
108
+ 0x53: [6, 8, 6, 8, -1],
109
+ 0x54: [6, 8, 6, 8, 10, 8, -1],
110
+ 0x55: [6, 8, 6, 8, -1],
111
+ 0x56: [6, 8, 0, 1, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 0, 5, 5, 5, 5, 0, 1, 6, 8, 1, 6, 8, 10, 8, 5, -1],
112
+ 0x57: [6, 8, 1, -1],
113
+ 0x58: [6, 8, 6, 8, -1],
114
+ 0x59: [6, 8, 6, 8, 1, -1],
115
+ 0x5A: [6, 8, 7, 1, -1],
116
+ 0x5B: [6, 8, 1, 0, -1],
117
+ 0x5C: [6, 8, -1],
118
+ 0x5D: [6, 8, 6, 8, 0, -1],
119
+ 0x5E: [6, 8, 5, 5, -1],
120
+ 0x5F: [10, 8, -1],
121
+ 0x60: [1, 1, 1, 1, -1],
122
+ 0x61: [0, 5, 5, 5, 5, -1],
123
+ 0x62: [6, 8, -1],
124
+ 0x63: [6, 8, 0, -1],
125
+ 0x64: [0, -1],
126
+ 0x65: [1, 0, 5, 5, 0, 10, 8, -1],
127
+ 0x66: [10, 8, -1],
128
+ 0x67: [0, 0, 1, 5, 5, 5, 5, 5, 0, -1],
129
+ 0x68: [0, -1],
130
+ 0x69: [6, 8, 0, 0, 5, 5, 5, 5, 5, 1, 5, -1],
131
+ 0x6A: [6, 8, 1, 0, 0, 10, 8, -1],
132
+ 0x6B: [6, 8, 6, 8, -1],
133
+ 0x6C: [6, 8, 5, 5, -1],
134
+ 0x6D: [6, 8, 5, 5, 0, 0, 0, -1],
135
+ 0x6E: [9, 8, 6, 8, -1],
136
+ 0x6F: [9, 8, -1],
137
+ 0x70: [9, 8, 1, -1],
138
+ 0x71: [-1],
139
+ 0x72: [9, 8, 1, 1, 9, 8, -1],
140
+ 0x73: [9, 8, 9, 8, 1, -1],
141
+ 0x74: [9, 8, 9, 8, -1],
142
+ 0x75: [9, 8, 6, 8, -1],
143
+ 0x78: [6, 8, 10, 8, 0, 0, 0, -1],
144
+ 0x79: [6, 8, 6, 8, 5, -1],
145
+ 0x7A: [6, 8, 10, 8, 5, 0, 0, 10, 8, -1],
146
+ 0x7B: [6, 8, 10, 8, -1],
147
+ 0x7C: [6, 8, 6, 8, 5, -1],
148
+ 0x7D: [6, 8, 5, -1],
149
+ 0x7E: [6, 8, -1],
150
+ 0x7F: [6, 8, 5, 5, 5, 5, 5, -1],
151
+ 0x80: [6, 8, -1],
152
+ 0x81: [6, 8, 0, 10, 8, 5, 5, 0, -1],
153
+ 0x82: [6, 8, 10, 8, 5, -1],
154
+ 0x83: [6, 8, 6, 8, 5, 5, -1],
155
+ 0x84: [6, 8, 6, 8, 6, 8, 5, 1, 5, -1],
156
+ 0x85: [6, 8, 6, 8, 0, 5, -1],
157
+ 0x86: [6, 8, 5, 5, 5, -1],
158
+ 0x87: [6, 8, 5, -1],
159
+ 0x88: [6, 8, 6, 8, 6, 8, 5, 1, 5, -1],
160
+ 0x89: [6, 8, 5, 5, -1],
161
+ 0x8A: [6, 8, 6, 8, 0, 0, 0, -1],
162
+ 0x8C: [6, 8, 10, 8, 6, 8, 0, 0, 6, 8, 10, 8, -1],
163
+ 0x8D: [4, 6, 8, 6, 8, 0, 0, 1, 10, 8, -1],
164
+ 0x8E: [4, 6, 8, 6, 8, 0, 0, 1, 10, 8, -1],
165
+ 0x8F: [6, 8, 10, 8, -1],
166
+ 0x90: [6, 8, -1],
167
+ 0x91: [-1],
168
+ 0x96: [1, 5, 5, 5, 5, -1],
169
+ 0x97: [1, 0, 5, 5, 5, 5, -1],
170
+ 0x98: [6, 8, 1, 0, 0, 5, 5, 5, 5, 5, 1, 5, -1],
171
+ 0x99: [6, 8, 1, 0, 0, 10, 8, -1],
172
+ 0x9A: [-1],
173
+ 0x9B: [6, 8, -1],
174
+ 0x9C: [6, 8, 10, 8, -1],
175
+ 0x9D: [6, 8, -1],
176
+ 0x9E: [6, 8, 0, -1],
177
+ 0x9F: [6, 8, 0, -1],
178
+ 0xA0: [5, 5, 5, 5, -1],
179
+ 0xA1: [-1],
180
+ 0xA5: [6, 8, 5, 5, 10, 8, 10, 8, 5, 0, 0, -1],
181
+ 0xA6: [6, 8, 1, 1, 0, 0, 5, 5, 5, 5, 5, 1, 5, -1],
182
+ 0xA7: [6, 8, 1, 1, 0, 0, 10, 8, -1],
183
+ 0xA8: [6, 8, 6, 8, 1, 1, 0, 0, 5, 5, 5, 5, 5, 1, 5, -1],
184
+ 0xA9: [6, 8, 6, 8, 1, 1, 0, 0, 10, 8, -1],
185
+ 0xAA: [1, 0, 0, 5, 5, 5, 5, 5, 1, 5, -1],
186
+ 0xAB: [1, 0, 0, -1],
187
+ 0xAC: [-1],
188
+ 0xAD: [1, -1],
189
+ 0xAE: [6, 8, 1, -1],
190
+ 0xAF: [1, 1, 5, 5, 5, 5, -1],
191
+ 0xB0: [6, 8, 1, 1, 5, 5, 5, 5, -1],
192
+ 0xB4: [6, 8, 10, 8, 0, 0, -1],
193
+ 0xB5: [6, 8, 6, 8, 0, 0, 5, 5, 5, 0, 0, 10, 8, -1],
194
+ 0xB6: [6, 8, 5, -1],
195
+ 0xB7: [6, 8, 5, -1],
196
+ 0xB8: [6, 8, -1],
197
+ 0xB9: [6, 8, 6, 8, -1],
198
+ 0xBA: [6, 8, 6, 8, 6, 8, -1],
199
+ 0xBB: [6, 8, 0, -1],
200
+ 0xBE: [6, 8, 10, 8, 0, 0, -1],
201
+ 0xBF: [6, 8, 6, 8, -1],
202
+ 0xC0: [6, 8, 6, 8, 0, 0, 0, 0, 10, 8, -1],
203
+ 0xC1: [6, 8, -1],
204
+ 0xC2: [6, 8, 6, 8, 1, 1, 0, 0, 0, -1],
205
+ 0xC3: [6, 8, 1, 1, 6, 8, -1],
206
+ 0xC8: [-1],
207
+ 0xC9: [6, 8, 6, 8, 1, 1, 1, 1, -1],
208
+ 0xCA: [6, 8, 6, 8, -1],
209
+ 0xCB: [6, 8, 0, 0, -1],
210
+ 0xCC: [-1],
211
+ 0xCD: [6, 8, 6, 8, 6, 8, 6, 8, 6, 8, 5, 0, -1],
212
+ 0xCE: [0, -1],
213
+ 0xCF: [6, 8, 6, 8, 5, -1],
214
+ 0xD0: [6, 8, 1, -1],
215
+ 0xD1: [6, 8, 1, -1],
216
+ 0xD2: [6, 8, -1],
217
+ 0xD3: [6, 8, -1],
218
+ 0xD4: [10, 8, 1, 1, -1],
219
+ 0xD5: [6, 8, 5, -1],
220
+ 0xD6: [6, 8, 10, 8, -1],
221
+ 0xDC: [6, 8, 10, 8, 0, 0, 5, 5, 5, 0, -1],
222
+ 0xDD: [6, 8, 5, 5, 5, 0, 5, 0, 10, 8, -1],
223
+ 0xDE: [6, 8, 1, 5, 5, 5, 0, 5, 0, 10, 8, -1],
224
+ 0xDF: [6, 8, -1],
225
+ 0xE0: [6, 8, 1, -1],
226
+ 0xE5: [4, 4, -1],
227
+ 0xE7: [-1],
228
+ 0xE8: [-1],
229
+ 0xE9: [0, -1],
230
+ 0xF0: [0, -1],
231
+ 0xF8: [-1],
232
+ 0xF9: [0, 10, 8, -1],
233
+ 0xFA: [-1],
234
+ 0xFB: [0, -1],
235
+ 0xFC: [1, -1],
236
+ 0xFD: [-1],
237
+ 0xFE: [6, 8, -1],
238
+ }
239
+
240
+ _SPECIAL = frozenset({0x01, 0x02, 0x06, 0x0F, 0xE6, 0xFF})
241
+
242
+
243
+ # ---------------------------------------------------------------------------
244
+ # Low-level helpers
245
+ # ---------------------------------------------------------------------------
246
+
247
+
248
+ def _read_str(data, pos):
249
+ """Read null-terminated UTF-16LE string starting at *pos*.
250
+
251
+ Returns ``(text, pos_after_null)``.
252
+ """
253
+ start = pos
254
+ while pos + 1 < len(data):
255
+ if data[pos] == 0 and data[pos + 1] == 0:
256
+ return data[start:pos].decode('utf-16-le'), pos + 2
257
+ pos += 2
258
+ msg = f'Unterminated UTF-16LE string at offset {start:#x}'
259
+ raise ValueError(msg)
260
+
261
+
262
+ def _encode_str(text):
263
+ """Encode *text* as UTF-16LE with null terminator."""
264
+ return text.encode('utf-16-le') + b'\x00\x00'
265
+
266
+
267
+ def _skip(data, pos, type_code):
268
+ """Skip one operand of *type_code* at *pos*. Returns new position."""
269
+ if type_code == 0:
270
+ return pos + 1
271
+ if type_code in (1, 2):
272
+ return pos + 2
273
+ if type_code in (3, 4, 5):
274
+ return pos + 4
275
+ if type_code in (6, 9, 10):
276
+ _, pos = _read_str(data, pos)
277
+ return pos
278
+ if type_code == 8:
279
+ return pos # marker, 0 bytes
280
+ msg = f'Unknown operand type {type_code}'
281
+ raise ValueError(msg)
282
+
283
+
284
+ def _ror2(b):
285
+ return ((b >> 2) | (b << 6)) & 0xFF
286
+
287
+
288
+ def _decrypt(data):
289
+ return bytes(_ror2(b) for b in data)
290
+
291
+
292
+ def _rol2(b):
293
+ return ((b << 2) | (b >> 6)) & 0xFF
294
+
295
+
296
+ def _encrypt(data):
297
+ return bytes(_rol2(b) for b in data)
298
+
299
+
300
+ def _ends_with_ff(data):
301
+ """Return True if *data* parses as a valid WS2 stream ending with 0xFF."""
302
+ try:
303
+ pos = 0
304
+ last_opcode = None
305
+ while pos < len(data):
306
+ opcode = data[pos]
307
+ last_opcode = opcode
308
+ pos += 1
309
+
310
+ if opcode == 0x01:
311
+ val = data[pos]
312
+ pos += 1
313
+ if val in (2, 128, 129, 130, 192) or (val == 3 and pos < len(data) and data[pos] in (50, 51, 127, 128)):
314
+ for tc in (1, 5, 4, 4):
315
+ pos = _skip(data, pos, tc)
316
+ elif opcode in (0x02, 0x06):
317
+ pos = _skip(data, pos, 4)
318
+ elif opcode == 0x0F:
319
+ count = data[pos]
320
+ pos += 1
321
+ for _ in range(count):
322
+ pos = _skip(data, pos, 1) # word
323
+ _, pos = _read_str(data, pos) # choice text
324
+ pos += 3 # op1, op2, op3
325
+ op_jump = data[pos]
326
+ pos += 1
327
+ if op_jump == 6:
328
+ pos = _skip(data, pos, 4)
329
+ elif op_jump == 7:
330
+ _, pos = _read_str(data, pos)
331
+ else:
332
+ return False
333
+ elif opcode == 0xE6:
334
+ pos = _skip(data, pos, 4)
335
+ pos = _skip(data, pos, 4)
336
+ elif opcode == 0xFF:
337
+ pos = _skip(data, pos, 4)
338
+ pos += 4
339
+ elif opcode in _SIGS:
340
+ sig = _SIGS[opcode]
341
+ i = 0
342
+ while i < len(sig):
343
+ tc = sig[i]
344
+ if tc == -1:
345
+ break
346
+ if tc == 7:
347
+ cnt = data[pos]
348
+ pos += 1
349
+ next_tc = sig[i + 1]
350
+ for _ in range(cnt):
351
+ pos = _skip(data, pos, next_tc)
352
+ i += 2
353
+ continue
354
+ pos = _skip(data, pos, tc)
355
+ i += 1
356
+ else:
357
+ return False
358
+ return last_opcode == 0xFF and pos == len(data)
359
+ except (ValueError, IndexError, struct.error):
360
+ return False
361
+
362
+
363
+ def _detect_encrypted(data):
364
+ """Return True if *data* appears to be ROL2-encrypted."""
365
+ if _ends_with_ff(data):
366
+ return False
367
+ if _ends_with_ff(_decrypt(data)):
368
+ return True
369
+ return False
370
+
371
+
372
+ # ---------------------------------------------------------------------------
373
+ # Intermediate file I/O
374
+ # ---------------------------------------------------------------------------
375
+
376
+
377
+ def _write_intermediate(chunks, fixups, encrypted):
378
+ """Serialize chunks and fixups into intermediate format."""
379
+ buf = BytesIO()
380
+ buf.write(MAGIC)
381
+ buf.write(struct.pack('<B', 1 if encrypted else 0))
382
+ buf.write(struct.pack('<I', len(chunks)))
383
+ buf.write(struct.pack('<I', len(fixups)))
384
+
385
+ for orig_offset, chunk_type, payload in chunks:
386
+ buf.write(struct.pack('<BI', chunk_type, orig_offset))
387
+ if chunk_type == _RAW:
388
+ buf.write(struct.pack('<I', len(payload)))
389
+ buf.write(payload)
390
+ else:
391
+ key, eol, orig_byte_len = payload
392
+ key_bytes = key.encode('ascii')
393
+ eol_bytes = eol.encode('ascii')
394
+ buf.write(struct.pack('<I', orig_byte_len))
395
+ buf.write(struct.pack('<H', len(key_bytes)))
396
+ buf.write(key_bytes)
397
+ buf.write(struct.pack('<H', len(eol_bytes)))
398
+ buf.write(eol_bytes)
399
+
400
+ for chunk_idx, offset_in_chunk in fixups:
401
+ buf.write(struct.pack('<II', chunk_idx, offset_in_chunk))
402
+
403
+ buf.seek(0)
404
+ return buf
405
+
406
+
407
+ def _read_intermediate(data):
408
+ """Deserialize intermediate format. Returns (chunks, fixups, encrypted)."""
409
+ pos = 0
410
+ if data[pos : pos + 4] != MAGIC:
411
+ msg = f"Invalid intermediate magic: {data[:4]!r}"
412
+ raise ValueError(msg)
413
+ pos += 4
414
+
415
+ encrypted = bool(data[pos])
416
+ pos += 1
417
+
418
+ num_chunks = struct.unpack_from('<I', data, pos)[0]
419
+ pos += 4
420
+ num_fixups = struct.unpack_from('<I', data, pos)[0]
421
+ pos += 4
422
+
423
+ chunks = []
424
+ for _ in range(num_chunks):
425
+ chunk_type = data[pos]
426
+ pos += 1
427
+ orig_offset = struct.unpack_from('<I', data, pos)[0]
428
+ pos += 4
429
+ if chunk_type == _RAW:
430
+ length = struct.unpack_from('<I', data, pos)[0]
431
+ pos += 4
432
+ payload = data[pos : pos + length]
433
+ pos += length
434
+ chunks.append((orig_offset, _RAW, payload))
435
+ else:
436
+ orig_byte_len = struct.unpack_from('<I', data, pos)[0]
437
+ pos += 4
438
+ key_len = struct.unpack_from('<H', data, pos)[0]
439
+ pos += 2
440
+ key = data[pos : pos + key_len].decode('ascii')
441
+ pos += key_len
442
+ eol_len = struct.unpack_from('<H', data, pos)[0]
443
+ pos += 2
444
+ eol = data[pos : pos + eol_len].decode('ascii')
445
+ pos += eol_len
446
+ chunks.append((orig_offset, chunk_type, (key, eol, orig_byte_len)))
447
+
448
+ fixups = []
449
+ for _ in range(num_fixups):
450
+ chunk_idx = struct.unpack_from('<I', data, pos)[0]
451
+ pos += 4
452
+ offset_in_chunk = struct.unpack_from('<I', data, pos)[0]
453
+ pos += 4
454
+ fixups.append((chunk_idx, offset_in_chunk))
455
+
456
+ return chunks, fixups, encrypted
457
+
458
+
459
+ # ---------------------------------------------------------------------------
460
+ # Parser
461
+ # ---------------------------------------------------------------------------
462
+
463
+
464
+ def _parse_file(data, ignore_patterns=()):
465
+ """Parse a decrypted WS2 file.
466
+
467
+ Returns ``(chunks, fixups, textlines)`` where:
468
+ - chunks: list of ``(orig_offset, type, payload)``
469
+ - fixups: list of ``(chunk_index, offset_in_chunk)`` for pointer values
470
+ - textlines: list of ``TextLine``
471
+ """
472
+ chunks = []
473
+ fixups = []
474
+ textlines = []
475
+ ptr_positions = [] # file offsets of pointer operands (pre-chunking)
476
+ line_index = 0
477
+ raw_start = 0 # start of the current uncommitted raw region
478
+
479
+ def _flush_raw(end):
480
+ """Emit raw bytes from raw_start..end and assign pending pointers."""
481
+ nonlocal raw_start
482
+ if end <= raw_start:
483
+ return
484
+ chunk_idx = len(chunks)
485
+ raw_data = data[raw_start:end]
486
+ chunks.append((raw_start, _RAW, raw_data))
487
+ # Assign pointer fixups that fall within this raw chunk
488
+ for pp in ptr_positions:
489
+ if raw_start <= pp < end:
490
+ fixups.append((chunk_idx, pp - raw_start))
491
+ raw_start = end
492
+
493
+ def _emit_text(text_type, string_start, string_end, text, eol):
494
+ nonlocal raw_start, line_index
495
+ _flush_raw(string_start)
496
+ key = f'<<<TRANS:{line_index}>>>'
497
+ orig_byte_len = string_end - string_start
498
+ chunks.append((string_start, text_type, (key, eol, orig_byte_len)))
499
+ textlines.append(TextLine(key, text, eol))
500
+ line_index += 1
501
+ raw_start = string_end
502
+
503
+ pos = 0
504
+ while pos < len(data):
505
+ opcode = data[pos]
506
+ pos += 1
507
+
508
+ if opcode == 0x14: # DisplayMessage
509
+ pos += 4 # skip sequence number (not a jump pointer)
510
+ _, pos = _read_str(data, pos) # skip variable name string
511
+ # marker (0 bytes)
512
+ dialogue_start = pos
513
+ dialogue_text, pos = _read_str(data, pos)
514
+ dialogue_end = pos
515
+ # marker (0 bytes)
516
+ pos += 1 # separator byte
517
+
518
+ eol_match = _EOL_RE.search(dialogue_text)
519
+ if eol_match:
520
+ eol = eol_match.group(1)
521
+ text = dialogue_text[: eol_match.start()]
522
+ else:
523
+ eol = ''
524
+ text = dialogue_text
525
+
526
+ if text and not TranslatableFile._should_ignore(text, ignore_patterns):
527
+ _emit_text(_DIALOGUE, dialogue_start, dialogue_end, text, eol)
528
+
529
+ elif opcode == 0x15: # SetDisplayName
530
+ name_start = pos
531
+ name_text, pos = _read_str(data, pos)
532
+ name_end = pos
533
+ # marker (0 bytes)
534
+ pos += 1 # separator byte
535
+
536
+ if name_text.startswith('%LF'):
537
+ name = name_text[3:]
538
+ if name and not TranslatableFile._should_ignore(name, ignore_patterns):
539
+ _emit_text(_NAME, name_start, name_end, name, '')
540
+
541
+ elif opcode == 0x0F: # ShowChoice (special)
542
+ count = data[pos]
543
+ pos += 1
544
+ for _ in range(count):
545
+ pos += 2 # word (choice id)
546
+ choice_start = pos
547
+ choice_text, pos = _read_str(data, pos)
548
+ choice_end = pos
549
+ pos += 3 # op1, op2, op3
550
+ op_jump = data[pos]
551
+ pos += 1
552
+ if op_jump == 6:
553
+ ptr_positions.append(pos)
554
+ pos += 4
555
+ elif op_jump == 7:
556
+ _, pos = _read_str(data, pos)
557
+
558
+ if choice_text and not TranslatableFile._should_ignore(choice_text, ignore_patterns):
559
+ _emit_text(_CHOICE, choice_start, choice_end, choice_text, '')
560
+
561
+ elif opcode == 0x01: # Condition (special)
562
+ val = data[pos]
563
+ pos += 1
564
+ if val in (2, 128, 129, 130, 192) or (val == 3 and pos < len(data) and data[pos] in (50, 51, 127, 128)):
565
+ pos = _skip(data, pos, 1) # word
566
+ pos = _skip(data, pos, 5) # float
567
+ ptr_positions.append(pos)
568
+ pos = _skip(data, pos, 4) # ptr
569
+ ptr_positions.append(pos)
570
+ pos = _skip(data, pos, 4) # ptr
571
+
572
+ elif opcode in (0x02, 0x06): # Jump (special)
573
+ ptr_positions.append(pos)
574
+ pos = _skip(data, pos, 4)
575
+
576
+ elif opcode == 0xE6: # ConditionalJump (special)
577
+ ptr_positions.append(pos)
578
+ pos = _skip(data, pos, 4)
579
+ ptr_positions.append(pos)
580
+ pos = _skip(data, pos, 4)
581
+
582
+ elif opcode == 0xFF: # FileEnd (special)
583
+ pos = _skip(data, pos, 4) # int
584
+ pos += 4 # 4 individual bytes
585
+
586
+ elif opcode in _SIGS:
587
+ sig = _SIGS[opcode]
588
+ i = 0
589
+ while i < len(sig):
590
+ tc = sig[i]
591
+ if tc == -1:
592
+ break
593
+ if tc == 7: # array
594
+ cnt = data[pos]
595
+ pos += 1
596
+ next_tc = sig[i + 1]
597
+ for _ in range(cnt):
598
+ pos = _skip(data, pos, next_tc)
599
+ i += 2
600
+ continue
601
+ pos = _skip(data, pos, tc)
602
+ i += 1
603
+ else:
604
+ msg = f'Unknown opcode {opcode:#x} at offset {pos - 1:#x}'
605
+ raise ValueError(msg)
606
+
607
+ # Flush remaining raw bytes
608
+ _flush_raw(len(data))
609
+
610
+ # Discard ptr_positions that weren't assigned (shouldn't happen, but be safe)
611
+ return chunks, fixups, textlines
612
+
613
+
614
+ # ---------------------------------------------------------------------------
615
+ # Handler class
616
+ # ---------------------------------------------------------------------------
617
+
618
+
619
+ class AdvHdWs2(TranslatableFile):
620
+ @staticmethod
621
+ def get_paths(workpath):
622
+ return list(workpath.glob('**/*.ws2'))
623
+
624
+ @classmethod
625
+ def extract_lines(cls, input_file, ignore_patterns=(), **kwargs):
626
+ raw_data = input_file.read()
627
+
628
+ encrypted = _detect_encrypted(raw_data)
629
+ data = _decrypt(raw_data) if encrypted else raw_data
630
+
631
+ chunks, fixups, textlines = _parse_file(data, ignore_patterns)
632
+ intermediate = _write_intermediate(chunks, fixups, encrypted)
633
+ return (intermediate, textlines, {})
634
+
635
+ @staticmethod
636
+ def insert_lines(intermediate_file, translation_dict):
637
+ idata = intermediate_file.read()
638
+ chunks, fixups, encrypted = _read_intermediate(idata)
639
+
640
+ # First pass: build output and offset mapping
641
+ output_parts = []
642
+ # Track (original_offset, original_size, new_size) for offset mapping
643
+ offset_records = []
644
+
645
+ for orig_offset, chunk_type, payload in chunks:
646
+ if chunk_type == _RAW:
647
+ new_bytes = bytearray(payload)
648
+ orig_size = len(payload)
649
+ else:
650
+ key, eol, orig_byte_len = payload
651
+ orig_size = orig_byte_len
652
+ trans = translation_dict.get(key)
653
+ if trans is not None:
654
+ text = trans.text
655
+ else:
656
+ text = key # fallback to key if no translation
657
+
658
+ if chunk_type == _DIALOGUE:
659
+ new_bytes = _encode_str(text + eol)
660
+ elif chunk_type == _NAME:
661
+ new_bytes = _encode_str('%LF' + text)
662
+ elif chunk_type == _CHOICE:
663
+ new_bytes = _encode_str(text)
664
+ else:
665
+ msg = f'Unknown chunk type {chunk_type}'
666
+ raise ValueError(msg)
667
+
668
+ offset_records.append((orig_offset, orig_size, len(new_bytes)))
669
+ output_parts.append(new_bytes)
670
+
671
+ # Build cumulative offset shift table for pointer fixup
672
+ # For each chunk: new_start = orig_offset + cumulative_shift
673
+ cumulative_shift = 0
674
+ shift_table = [] # (original_offset, shift)
675
+ for orig_offset, orig_size, new_size in offset_records:
676
+ shift_table.append((orig_offset, cumulative_shift))
677
+ cumulative_shift += new_size - orig_size
678
+
679
+ def _map_offset(old_offset):
680
+ """Map an original byte offset to its new position."""
681
+ # Find the last shift entry with original_offset <= old_offset
682
+ best_shift = 0
683
+ for entry_offset, shift in shift_table:
684
+ if entry_offset <= old_offset:
685
+ best_shift = shift
686
+ else:
687
+ break
688
+ return old_offset + best_shift
689
+
690
+ # Second pass: fix up pointer values in raw chunks
691
+ for chunk_idx, offset_in_chunk in fixups:
692
+ raw_bytes = output_parts[chunk_idx]
693
+ old_ptr = struct.unpack_from('<I', raw_bytes, offset_in_chunk)[0]
694
+ if old_ptr == 0:
695
+ continue # null pointers don't need fixup
696
+ new_ptr = _map_offset(old_ptr)
697
+ struct.pack_into('<I', raw_bytes, offset_in_chunk, new_ptr)
698
+
699
+ # Assemble final output
700
+ output = BytesIO()
701
+ for part in output_parts:
702
+ output.write(bytes(part))
703
+
704
+ if encrypted:
705
+ output.seek(0)
706
+ output = BytesIO(_encrypt(output.read()))
707
+
708
+ output.seek(0)
709
+ return output