tfbscript 0.1.0__py3-none-any.whl

tfbscript/opcodes/op_change_membership.py

@@ -0,0 +1,62 @@
+from dataclasses import dataclass, field
+from typing import Any, BinaryIO, override
+
+from tfbscript.ansi import method, parentheses
+from tfbscript.binary import write_u8
+from tfbscript.opcodes.base import Opcode, opcode
+from tfbscript.opcodes.enums import MembershipCombiner
+from tfbscript.payload import PayloadReader
+from tfbscript.reference import Reference
+
+
+@opcode("change membership")
+@dataclass
+class OpChangeMembership(Opcode):
+    ref: Reference = field(default_factory=Reference)
+    membershipCombiner: MembershipCombiner = field(default=MembershipCombiner.add)
+    ref2: Reference = field(default_factory=Reference)
+
+    @classmethod
+    @override
+    def parse_payload(cls, reader: PayloadReader) -> "OpChangeMembership":
+        ref = reader.readRef()
+        membershipCombiner = MembershipCombiner(reader.read_u8())
+        ref2 = reader.readRef()
+        return cls(ref=ref, membershipCombiner=membershipCombiner, ref2=ref2)
+
+    @override
+    def source_line(self, inline: bool = False) -> str:
+        return f"{self.ref}.{method(self.membershipCombiner.symbol())}{parentheses('(')}{self.ref2}{parentheses(')')};"
+
+    @override
+    def write_payload(self, f: BinaryIO) -> None:
+        self.ref.write(f)
+        write_u8(f, self.membershipCombiner)
+        self.ref2.write(f)
+
+    @override
+    def editor_repr(self) -> dict[str, Any]:
+        return {
+            "fields": [
+                {
+                    "type": "op-label",
+                    "value": "set [set]",
+                },
+                {
+                    "type": "ref",
+                    "ref": self.ref,
+                },
+                {
+                    "type": "label",
+                    "content": "to",
+                },
+                {
+                    "type": "enum",
+                    "value": self.membershipCombiner,
+                },
+                {
+                    "type": "ref",
+                    "ref": self.ref2,
+                },
+            ]
+        }

tfbscript/opcodes/op_check_fov.py

@@ -0,0 +1,73 @@
+from dataclasses import dataclass, field
+from typing import BinaryIO, override
+
+from tfbscript.ansi import comparison, keyword, number
+from tfbscript.binary import write_u8
+from tfbscript.opcodes.base import Opcode, opcode
+from tfbscript.opcodes.enums import CheckFOVMode, RelOp
+from tfbscript.payload import PayloadReader
+from tfbscript.reference import Reference
+from tfbscript.rhs import Rhs
+
+
+@opcode(
+    "check fov",
+    """
+        Is there an actor from target_ref within arc_width°
+        of angle_base, whose distance to me satisfies
+        "distance {range_relop} range",
+        and if mode == consider_obstructions,
+        i have a clear line of sight to them?
+        """,
+)
+@dataclass
+class OpCheckFOV(Opcode):
+    angle_base: Rhs = field(default_factory=Rhs)
+    arc_width: Rhs = field(default_factory=Rhs)
+
+    target_ref: Reference = field(default_factory=Reference)
+
+    range_relop: RelOp = RelOp.Eq
+    range: Rhs = field(default_factory=Rhs)
+
+    mode: CheckFOVMode = CheckFOVMode.ignore_obstructions
+
+    @classmethod
+    @override
+    def parse_payload(cls, reader: PayloadReader) -> "OpCheckFOV":
+        angle_base = reader.readRHS()
+        arc_width = reader.readRHS()
+
+        target_ref = reader.readRef()
+
+        range_relop = RelOp(reader.read_u8())
+        range = reader.readRHS()
+
+        checkfov_mode = CheckFOVMode(reader.read_u8())
+
+        return cls(
+            angle_base=angle_base,
+            arc_width=arc_width,
+            target_ref=target_ref,
+            range_relop=range_relop,
+            range=range,
+            mode=checkfov_mode,
+        )
+
+    @override
+    def source_line(self, inline: bool = False) -> str:
+        condition = f"{self.target_ref} is within a {number(self.arc_width)}° cone centered on heading {number(self.angle_base)}, distance {comparison(self.range_relop.symbol())} {self.range}, {self.mode}"
+
+        # Normally we would have a check for inline here,
+        # but its nice to know that this is a FOV check
+
+        return f"{keyword('check fov (')} {condition} {keyword(')')}"
+
+    @override
+    def write_payload(self, f: BinaryIO) -> None:
+        self.angle_base.write(f)
+        self.arc_width.write(f)
+        self.target_ref.write(f)
+        write_u8(f, self.range_relop)
+        self.range.write(f)
+        write_u8(f, self.mode)

tfbscript/opcodes/op_check_membership.py

@@ -0,0 +1,41 @@
+from dataclasses import dataclass, field
+from typing import BinaryIO, override
+
+from tfbscript.ansi import comparison, keyword
+from tfbscript.binary import write_u8
+from tfbscript.opcodes.base import Opcode, opcode
+from tfbscript.opcodes.enums import MembershipTest
+from tfbscript.payload import PayloadReader
+from tfbscript.reference import Reference
+
+
+@opcode("check membership")
+@dataclass
+class OpCheckMembership(Opcode):
+    ref1: Reference = field(default_factory=Reference)
+    membershipTest: MembershipTest = MembershipTest.includes
+    ref2: Reference = field(default_factory=Reference)
+
+    @classmethod
+    @override
+    def parse_payload(cls, reader: PayloadReader) -> "OpCheckMembership":
+        ref1 = reader.readRef()
+        membershipTest = MembershipTest(reader.read_u8())
+        ref2 = reader.readRef()
+        return cls(ref1=ref1, membershipTest=membershipTest, ref2=ref2)
+
+    @override
+    def source_line(self, inline: bool = False) -> str:
+        condition = (
+            f"{self.ref1} {comparison(self.membershipTest.symbol())} {self.ref2}"
+        )
+        if inline:
+            return condition
+
+        return f"{keyword('check membership (')} {condition} {keyword(')')}"
+
+    @override
+    def write_payload(self, f: BinaryIO) -> None:
+        self.ref1.write(f)
+        write_u8(f, self.membershipTest)
+        self.ref2.write(f)

tfbscript/opcodes/op_check_message.py

@@ -0,0 +1,79 @@
+from dataclasses import dataclass, field
+from typing import BinaryIO, override
+
+from tfbscript.ansi import keyword
+from tfbscript.binary import write_u8
+from tfbscript.opcodes.base import Opcode, opcode
+from tfbscript.opcodes.enums import RelOp
+from tfbscript.payload import PayloadReader
+from tfbscript.reference import Reference
+from tfbscript.rhs import Rhs
+
+
+@opcode("check message")
+@dataclass
+class OpCheckMessage(Opcode):
+    message_ref: Reference = field(default_factory=Reference)
+
+    sender_ref: Reference = field(default_factory=Reference)
+    rel_op: RelOp = field(default=RelOp.Eq)
+    value: Rhs = field(default_factory=Rhs)
+
+    _is_extended: bool = field(
+        default=False
+    )  # has sender_ref, rel_op, value determined if payload > 4
+
+    @classmethod
+    @override
+    def parse_payload(cls, reader: PayloadReader) -> "OpCheckMessage":
+        message_ref = reader.readRef()
+
+        # Three shapes only, 4 / 14 / 20 bytes, so this threshold cannot be
+        # straddled. The engine's own test is not reproducible from the .ai:
+        # parse (FUN_0043AE30) asks the message's descriptor
+        # DAT_0061f870->vt[0x18]() and stops right after the message ref when
+        # that is <= 0 -- an operand count that comes from the message's
+        # per-level declaration in the level hub, not from this file. The two
+        # `message` vtables differ only there: 005CDC08 returns 0, 005CE590
+        # returns 2. Verified as a per-declaration property: of 88 message
+        # symbols, 79 are always extended and 8 always plain; the one that is
+        # both (`ledge nearby`) is plain in 8 levels and extended in `battle`.
+        #
+        # Ref: 4b
+        # RelOp: 1b
+        # Rhs: min. 5b
+        if reader.size_remaining() >= 4 + 1 + 5:
+            sender_ref = reader.readRef()
+
+            rel_op = RelOp(reader.read_u8())
+            value = reader.readRHS()
+
+            return cls(
+                message_ref=message_ref,
+                sender_ref=sender_ref,
+                rel_op=rel_op,
+                value=value,
+                _is_extended=True,
+            )
+
+        return cls(
+            message_ref=message_ref,
+            _is_extended=False,
+        )
+
+    @override
+    def write_payload(self, f: BinaryIO) -> None:
+        self.message_ref.write(f)
+        if not self._is_extended:
+            return
+        self.sender_ref.write(f)
+        write_u8(f, self.rel_op)
+        self.value.write(f)
+
+    @override
+    def source_line(self, inline: bool = False) -> str:
+        if self._is_extended:
+            condition = f"value {self.rel_op} {self.value}"
+            return f"{keyword('check message (')} {self.message_ref}, sent by: {self.sender_ref}, where: {condition} {keyword(')')}"
+        else:
+            return f"{keyword('check message (')} {self.message_ref} {keyword(')')}"

tfbscript/opcodes/op_check_reference.py

@@ -0,0 +1,61 @@
+from dataclasses import dataclass, field
+from typing import Any, BinaryIO, override
+
+from tfbscript.ansi import keyword
+from tfbscript.opcodes.base import Opcode, opcode
+from tfbscript.payload import PayloadReader
+from tfbscript.reference import Reference
+
+
+@opcode("check reference")
+@dataclass
+class OpCheckReference(Opcode):
+    ref1: Reference = field(default_factory=Reference)
+    ref2: Reference = field(default_factory=Reference)
+
+    @classmethod
+    @override
+    def parse_payload(cls, reader: PayloadReader) -> "OpCheckReference":
+        ref1 = reader.readRef()
+        ref2 = reader.readRef()
+
+        return cls(ref1=ref1, ref2=ref2)
+
+    @override
+    def write_payload(self, f: BinaryIO) -> None:
+        self.ref1.write(f)
+        self.ref2.write(f)
+
+    @override
+    def source_line(self, inline: bool = False) -> str:
+        condition = f"*{self.ref1} is reference to {self.ref2}"
+        if inline:
+            return condition
+
+        return f"{keyword('check reference (')} {condition} {keyword(')')}"
+
+    @override
+    def editor_repr(self) -> dict[str, Any]:
+        return {
+            "hasBody": True,
+            "fields": [
+                {
+                    "type": "op-label",
+                    "value": "check reference",
+                },
+                {
+                    "type": "ref",
+                    "name": "ref1",
+                    "ref": self.ref1,
+                },
+                {
+                    "type": "op-label",
+                    "value": "is reference to",
+                },
+                {
+                    "type": "ref",
+                    "name": "ref2",
+                    "ref": self.ref2,
+                },
+            ],
+        }

tfbscript/opcodes/op_check_value.py

@@ -0,0 +1,66 @@
+from dataclasses import dataclass, field
+from typing import Any, BinaryIO, override
+
+from tfbscript.ansi import comparison, keyword
+from tfbscript.binary import write_u8
+from tfbscript.opcodes.base import Opcode, opcode
+from tfbscript.opcodes.enums import RelOp
+from tfbscript.payload import PayloadReader
+from tfbscript.reference import Reference
+from tfbscript.rhs import Rhs
+
+
+@opcode("check value")
+@dataclass
+class OpCheckValue(Opcode):
+    lhs: Reference = field(default_factory=Reference)
+    rel_op: RelOp = RelOp.Eq
+    rhs: Rhs = field(default_factory=Rhs)
+
+    @classmethod
+    @override
+    def parse_payload(cls, reader: PayloadReader) -> "OpCheckValue":
+        lhs = reader.readRef()
+        rel_op = RelOp(reader.read_u8())
+        rhs = reader.readRHS()
+        return cls(lhs=lhs, rel_op=rel_op, rhs=rhs)
+
+    @override
+    def source_line(self, inline: bool = False) -> str:
+        condition = f"{self.lhs} {comparison(self.rel_op.symbol())} {self.rhs}"
+        if inline:
+            return condition
+
+        return f"{keyword('check value (')} {condition} {keyword(')')}"
+
+
+    @override
+    def editor_repr(self) -> dict[str, Any]:
+        return {
+            "hasBody": True,
+            "fields": [
+                {
+                    "type": "op-label",
+                    "value": "check value",
+                },
+                {
+                    "type": "ref",
+                    "ref": self.lhs,
+                },
+                {
+                    "type": "enum",
+                    "name": "rel_op",
+                    "entry": self.rel_op,
+                },
+                {
+                    "type": "rhs",
+                    "rhs": self.rhs,
+                },
+            ]
+        }
+
+    @override
+    def write_payload(self, f: BinaryIO) -> None:
+        self.lhs.write(f)
+        write_u8(f, self.rel_op.value)
+        self.rhs.write(f)

tfbscript/opcodes/op_comment.py

@@ -0,0 +1,43 @@
+from dataclasses import dataclass
+from typing import Any, BinaryIO, override
+
+from tfbscript.ansi import comment
+from tfbscript.binary import write_u8
+from tfbscript.opcodes.base import Opcode, opcode
+from tfbscript.payload import PayloadReader
+
+
+@opcode("comment:")
+@dataclass
+class OpComment(Opcode):
+    content: str = ""
+
+    @classmethod
+    @override
+    def parse_payload(cls, reader: PayloadReader) -> "OpComment":
+        content = reader.read_string(reader.read_u8())
+        return cls(content=content)
+
+    @override
+    def source_line(self, inline: bool = False) -> str:
+        return comment(f"// {self.content}")
+
+    @override
+    def editor_repr(self) -> dict[str, Any]:
+        return {
+            "fields": [
+                {
+                    "type": "label",
+                    "content": "comment:",
+                },
+                {
+                    "type": "string",
+                    "value": self.content,
+                },
+            ]
+        }
+    
+    @override
+    def write_payload(self, f: BinaryIO) -> None:
+        write_u8(f, len(self.content))
+        f.write(self.content.encode("latin1"))

tfbscript/opcodes/op_control.py

@@ -0,0 +1,80 @@
+from dataclasses import dataclass, field
+from typing import Any, BinaryIO, override
+
+from tfbscript.ansi import keyword
+from tfbscript.binary import write_u8
+from tfbscript.opcodes.base import Opcode, opcode
+from tfbscript.opcodes.enums import ControlRequirement
+from tfbscript.payload import PayloadReader
+from tfbscript.reference import Reference
+
+
+@opcode("control")
+@dataclass
+class OpControl(Opcode):
+    target: Reference = field(default_factory=Reference)
+    script_control: ControlRequirement = field(default=ControlRequirement.Allow)
+
+    # Whether the payload carries the script_control byte. The byte is there
+    # for an actor target, but the target's type is the wrong thing to ask:
+    # resolving it only works while the read traversal is still inside the
+    # enclosing ops (see ParserContext.open_opcodes), so writing -- which
+    # happens outside any traversal -- got a different answer and dropped the
+    # byte. The payload length says it outright, there being only two shapes,
+    # 4 bytes for the reference alone and 5 with the byte. Measured over the
+    # corpus: 12,376 control ops, 965 of them 4 bytes and 11,411 of them 5,
+    # nothing else -- and the type test disagreed with the bytes 72 times.
+    _has_script_control: bool = True
+
+    @classmethod
+    @override
+    def parse_payload(cls, reader: PayloadReader) -> "OpControl":
+        target = reader.readRef()
+
+        script_control = ControlRequirement.Allow
+        has_script_control = reader.size_remaining() >= 1
+
+        if has_script_control:
+            script_control = ControlRequirement(reader.read_u8())
+
+        return cls(
+            target=target,
+            script_control=script_control,
+            _has_script_control=has_script_control,
+        )
+
+    @override
+    def source_line(self, inline: bool = False) -> str:
+        return f"{keyword('control (')} {self.target}, {self.script_control} {keyword(')')}"
+
+    @override
+    def write_payload(self, f: BinaryIO) -> None:
+        self.target.write(f)
+        if self._has_script_control:
+            write_u8(f, self.script_control)
+
+    @override
+    def editor_repr(self) -> dict[str, Any]:
+        return {
+            "hasBody": True,
+            "fields": [
+                {
+                    "type": "op-label",
+                    "value": "control",
+                },
+                {
+                    "type": "ref",
+                    "name": "target",
+                    "ref": self.target,
+                },
+                {
+                    "type": "op-label",
+                    "value": "script control: ",
+                },
+                {
+                    "type": "enum",
+                    "name": "script_control",
+                    "entry": self.script_control,
+                },
+            ],
+        }

tfbscript/opcodes/op_create_variable.py

@@ -0,0 +1,42 @@
+from dataclasses import dataclass, field
+from typing import Any, BinaryIO, override
+
+from tfbscript.ansi import keyword, type_
+from tfbscript.opcodes.base import Opcode, opcode
+from tfbscript.payload import PayloadReader
+from tfbscript.reference import Reference
+
+
+@opcode("create variable")
+@dataclass
+class OpCreateVariable(Opcode):
+    variable: Reference = field(default_factory=Reference)
+
+    @classmethod
+    @override
+    def parse_payload(cls, reader: PayloadReader) -> "OpCreateVariable":
+        return cls(variable=reader.readRef())
+
+    @override
+    def source_line(self, inline: bool = False) -> str:
+        var_type = self.variable.entry.type if self.variable.entry else "unknown"
+        return f"{keyword('var')} {self.variable} : {type_(var_type)};"
+
+    @override
+    def editor_repr(self) -> dict[str, Any]:
+        return {
+            "fields": [
+                {
+                    "type": "op-label",
+                    "value": "create variable",
+                },
+                {
+                    "type": "ref",
+                    "ref": self.variable,
+                },
+            ]
+        }
+
+    @override
+    def write_payload(self, f: BinaryIO) -> None:
+        self.variable.write(f)

tfbscript/opcodes/op_cut_scene.py

@@ -0,0 +1,44 @@
+from dataclasses import dataclass, field
+from typing import Any, BinaryIO, override
+
+from tfbscript.ansi import func_call
+from tfbscript.binary import write_u8
+from tfbscript.opcodes.base import Opcode, opcode
+from tfbscript.opcodes.enums import CutsceneCommand
+from tfbscript.payload import PayloadReader
+
+@opcode("cut-scene")
+@dataclass
+class OpCutScene(Opcode):
+    cutscene_command: CutsceneCommand = field(default=CutsceneCommand.Begin)
+
+    @classmethod
+    @override
+    def parse_payload(cls, reader: PayloadReader) -> "OpCutScene":
+        cutscene_cmd = CutsceneCommand(reader.read_u8())
+        return cls(cutscene_command=cutscene_cmd)
+
+    @override
+    def source_line(self, inline: bool = False) -> str:
+        return func_call("cutScene", str(self.cutscene_command))
+
+    @override
+    def editor_repr(self) -> dict[str, Any]:
+        return {
+            "hasBody": False,
+            "fields": [
+                {
+                    "type": "op-label",
+                    "value": "cut-scene",
+                },
+                {
+                    "type": "enum",
+                    "name": "cutscene_command",
+                    "entry": self.cutscene_command,
+                },
+            ]
+        }
+
+    @override
+    def write_payload(self, f: BinaryIO) -> None:
+        write_u8(f, self.cutscene_command)

tfbscript/opcodes/op_dec_value.py

@@ -0,0 +1,43 @@
+from dataclasses import dataclass, field
+from typing import Any, BinaryIO, override
+
+from tfbscript.ansi import operator
+from tfbscript.opcodes.base import Opcode, opcode
+from tfbscript.payload import PayloadReader
+from tfbscript.reference import Reference
+
+
+@opcode("dec value")
+@dataclass
+class OpDecValue(Opcode):
+    lhs: Reference = field(default_factory=Reference)
+
+    @classmethod
+    @override
+    def parse_payload(cls, reader: PayloadReader) -> "OpDecValue":
+        return cls(lhs=reader.readRef())
+
+    @override
+    def source_line(self, inline: bool = False) -> str:
+        return f"{self.lhs} {operator('--')};"
+
+    @override
+    def editor_repr(self) -> dict[str, Any]:
+        return {
+            "hasBody": False,
+            "fields": [
+                {
+                    "type": "op-label",
+                    "value": "decrement value",
+                },
+                {
+                    "type": "ref",
+                    "name": "lhs",
+                    "ref": self.lhs,
+                },
+            ]
+        }
+
+    @override
+    def write_payload(self, f: BinaryIO) -> None:
+        self.lhs.write(f)