diff --git a/Code/BF2/Game/GeneralSettings.cpp b/Code/BF2/Game/GeneralSettings.cpp index fc316a1de..a6b176494 100644 --- a/Code/BF2/Game/GeneralSettings.cpp +++ b/Code/BF2/Game/GeneralSettings.cpp @@ -315,7 +315,9 @@ const float kByteToUnit = 0.0039215689f; GeneralSettings::GeneralSettings() : m_refCount(1) { m_lcdDisplayModes = false; - m_toggleFilters = 63616; + // [CHOSEN, not recovered] Retail seeds 63616 (PunkBuster, all map sizes, same version and + // same mod); new profiles start with no server browser filters. See docs/server-browser-filters.md. + m_toggleFilters = 0; setDefaults(); } @@ -485,7 +487,9 @@ void GeneralSettings::setDefaultValues() m_allowPunkBuster = true; m_itemSelectionReverseItems = true; m_autoReload = true; - m_toggleFilters = 63616; + // [CHOSEN, not recovered] Retail seeds 63616; new profiles start with no server browser + // filters. See docs/server-browser-filters.md. + m_toggleFilters = 0; } // Reloads General.con to discard unsaved options while retaining server-browser and diff --git a/Code/Tests/general_settings_runtime.cpp b/Code/Tests/general_settings_runtime.cpp index 581e8e74d..e1b4e020e 100644 --- a/Code/Tests/general_settings_runtime.cpp +++ b/Code/Tests/general_settings_runtime.cpp @@ -80,7 +80,7 @@ static bool optionDefaults(GeneralSettings& g) && F::minimapTransparency(g)==204.0f && F::viewIntroMovie(g) && !F::outOfVoting(g) && F::bftv(g).empty() && !F::confirmQuit(g) && !F::lcdDisplayModes(g) && F::mapIconAlpha(g)==255.0f && F::allowPunkBuster(g) && F::itemSelectionReverseItems(g) - && F::autoReload(g) && F::toggleFilters(g)==63616; + && F::autoReload(g) && F::toggleFilters(g)==0; } // The remainder setDefaults (+1C) owns before dispatching +20. static bool outerDefaults(GeneralSettings& g,int earliest,int latest) @@ -101,7 +101,7 @@ static std::string defaultScript(int date) "GeneralSettings.setBFTVSaveDirectory \"\"\nGeneralSettings.setConfirmQuit 0\nGeneralSettings.setMapIconAlphaTransparency 255\n" "GeneralSettings.setUseAdvancedServerBrowser 0\nGeneralSettings.setUseBots 0\nGeneralSettings.setMaxBots 64\n" "GeneralSettings.setMaxBotsIncludeHumans 0\nGeneralSettings.setBotSkill 0.5\n")+row+ - "GeneralSettings.setAllowPunkBuster 1\nGeneralSettings.setItemSelectionReverseItems 1\nGeneralSettings.setToggleFilters 63616\n" + "GeneralSettings.setAllowPunkBuster 1\nGeneralSettings.setItemSelectionReverseItems 1\nGeneralSettings.setToggleFilters 0\n" "GeneralSettings.setAutoReload 1\nGeneralSettings.setAutoReady 0\nGeneralSettings.setConnectionType 5\nGeneralSettings.setLCDDisplayModes 0\n"; } static void scramble(GeneralSettings& g) diff --git a/Code/Tools/SwfDisasm/avm1_disasm.py b/Code/Tools/SwfDisasm/avm1_disasm.py new file mode 100644 index 000000000..56be4ec38 --- /dev/null +++ b/Code/Tools/SwfDisasm/avm1_disasm.py @@ -0,0 +1,229 @@ +#!/usr/bin/env python +"""Linear AVM1 (ActionScript 1/2) disassembler for Battlefield 2 Flash menu movies. + +The BF2 menus (for example External/FlashMenu/mainMenu.swf inside a mod's +menu_client.zip) call the engine through dice.bf2.* methods. This tool lists the +action stream of every DoAction, DoInitAction and nested DefineSprite tag, with +ConstantPool references resolved, so the arguments the movie passes to the +engine can be read directly. + +Limitations: actions attached to buttons (DefineButton2) and clip events +(PlaceObject2/3) are not decoded. Disassembly is linear; function bodies appear +in place after their DefineFunction/DefineFunction2 line. Branch targets are not +resolved. + +Usage: + python avm1_disasm.py [-o OUT] [--member PATH] + +When given a .zip, every .swf member is disassembled (or only --member). Output +lines have the form " ", where the tag path is +/DoAction, /Init or /S/DoAction. Works with Python 2.7 +and Python 3. +""" + +from __future__ import print_function + +import argparse +import struct +import sys +import zipfile +import zlib + +ACTION_NAMES = { + 0x04: 'NextFrame', 0x05: 'PrevFrame', 0x06: 'Play', 0x07: 'Stop', + 0x0A: 'Add', 0x0B: 'Subtract', 0x0C: 'Multiply', 0x0D: 'Divide', + 0x0E: 'Equals', 0x0F: 'Less', 0x10: 'And', 0x11: 'Or', 0x12: 'Not', + 0x13: 'StringEquals', 0x14: 'StringLength', 0x15: 'StringExtract', + 0x17: 'Pop', 0x18: 'ToInteger', 0x1C: 'GetVariable', 0x1D: 'SetVariable', + 0x20: 'SetTarget2', 0x21: 'StringAdd', 0x22: 'GetProperty', 0x23: 'SetProperty', + 0x24: 'CloneSprite', 0x25: 'RemoveSprite', 0x26: 'Trace', 0x27: 'StartDrag', + 0x28: 'EndDrag', 0x29: 'StringLess', 0x2A: 'Throw', 0x2B: 'CastOp', + 0x2C: 'ImplementsOp', 0x30: 'RandomNumber', 0x34: 'GetTime', + 0x3A: 'Delete', 0x3B: 'Delete2', 0x3C: 'DefineLocal', 0x3D: 'CallFunction', + 0x3E: 'Return', 0x3F: 'Modulo', 0x40: 'NewObject', 0x41: 'DefineLocal2', + 0x42: 'InitArray', 0x43: 'InitObject', 0x44: 'TypeOf', 0x45: 'TargetPath', + 0x46: 'Enumerate', 0x47: 'Add2', 0x48: 'Less2', 0x49: 'Equals2', + 0x4A: 'ToNumber', 0x4B: 'ToString', 0x4C: 'PushDuplicate', 0x4D: 'StackSwap', + 0x4E: 'GetMember', 0x4F: 'SetMember', 0x50: 'Increment', 0x51: 'Decrement', + 0x52: 'CallMethod', 0x53: 'NewMethod', 0x54: 'InstanceOf', 0x55: 'Enumerate2', + 0x60: 'BitAnd', 0x61: 'BitOr', 0x62: 'BitXor', 0x63: 'BitLShift', + 0x64: 'BitRShift', 0x65: 'BitURShift', 0x66: 'StrictEquals', 0x67: 'Greater', + 0x68: 'StringGreater', 0x69: 'Extends', + 0x81: 'GotoFrame', 0x83: 'GetURL', 0x87: 'StoreRegister', 0x88: 'ConstantPool', + 0x8A: 'WaitForFrame', 0x8B: 'SetTarget', 0x8C: 'GoToLabel', 0x8D: 'WaitForFrame2', + 0x8E: 'DefineFunction2', 0x8F: 'Try', 0x94: 'With', 0x96: 'Push', 0x99: 'Jump', + 0x9A: 'GetURL2', 0x9B: 'DefineFunction', 0x9D: 'If', 0x9E: 'Call', + 0x9F: 'GotoFrame2', +} + +TAG_END, TAG_SHOW_FRAME, TAG_DO_ACTION = 0, 1, 12 +TAG_DEFINE_SPRITE, TAG_FRAME_LABEL, TAG_DO_INIT_ACTION = 39, 43, 59 + + +def _cstr(data, start): + """Returns (text, index after the terminating NUL) for a NUL-terminated string.""" + end = data.index(b'\0', start) + return data[start:end].decode('latin-1'), end + 1 + + +def _push_operands(body, pool): + values = [] + j = 0 + while j < len(body): + kind = body[j] + j += 1 + if kind == 0: + text, j = _cstr(body, j) + values.append(repr(str(text))) + elif kind == 1: + values.append(repr(struct.unpack('' % kind) + break + return values + + +def disassemble_actions(data, tag_path, out): + """Appends one line per action in an action record stream.""" + pool = [] + i = 0 + while i < len(data): + code = data[i] + i += 1 + if code == 0: + out.append('%s End' % tag_path) + continue + length = 0 + if code >= 0x80: + length = struct.unpack(' Frame " line, followed by + its label when the frame has one, so frame actions can be tied to the + gotoAndStop/gotoAndPlay targets that reach them. + """ + frame = 1 + out.append('%s Frame %d' % (tag_path or '/', frame)) + i = 0 + while i + 2 <= len(data): + header = struct.unpack('> 6, header & 0x3F + if length == 0x3F: + length = struct.unpack('> 3 + rect_bytes = (5 + 4 * rect_bits + 7) // 8 + out = [] + walk_tags(raw[8 + rect_bytes + 4:], '', out) + return out + + +def main(argv=None): + parser = argparse.ArgumentParser(description=__doc__.split('\n\n')[0]) + parser.add_argument('input', help='an .swf file, or a .zip archive containing .swf members') + parser.add_argument('-o', '--output', help='write the listing here instead of stdout') + parser.add_argument('--member', help='zip member to disassemble (default: every .swf member)') + args = parser.parse_args(argv) + + lines = [] + if args.input.lower().endswith('.zip'): + archive = zipfile.ZipFile(args.input) + names = [args.member] if args.member else [ + n for n in archive.namelist() if n.lower().endswith('.swf')] + for name in names: + lines.append('# %s' % name) + lines.extend(disassemble_swf(archive.read(name))) + else: + with open(args.input, 'rb') as handle: + lines = disassemble_swf(handle.read()) + + text = '\n'.join(lines) + '\n' + if args.output: + with open(args.output, 'w') as handle: + handle.write(text) + else: + sys.stdout.write(text) + return 0 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/docs/README.md b/docs/README.md index 36da333b3..ef1353716 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,6 +13,7 @@ contribution workflow and validation requirements. | Engine images, source layout and lifecycle | [Engine architecture](architecture.md) | | Recovery prerequisites, contribution rules and validation | [Development guide](development.md) | | Editor console commands and script undo | [Editor console guide](editor-console.md) | +| Server browser filter mask and menu ActionScript tool | [Server browser filters](server-browser-filters.md) | [AGENTS.md](../AGENTS.md) is the working policy. Third-party documentation stays with its dependency under `Code/BF2/External/`. The validation commands are in the development guide, diff --git a/docs/server-browser-filters.md b/docs/server-browser-filters.md new file mode 100644 index 000000000..361ebeb0f --- /dev/null +++ b/docs/server-browser-filters.md @@ -0,0 +1,122 @@ +# Server browser filters + +The internet server browser's filter checkboxes are stored as one integer bit mask in the +profile's `General.con`: + +``` +GeneralSettings.setToggleFilters 63616 +``` + +The engine does not define what the bits mean. `GeneralSettings` only stores, tests and sets +them. The meaning of each bit, and the query clause it adds, come from the Flash main menu +(`External/FlashMenu/mainMenu.swf` in the mod's `menu_client.zip`). + +## Bit assignments + +The masks and clauses below are taken from the menu's ActionScript. The retail BF2 +`mods/bf2/Menu_client.zip` and Forgotten Hope 2 `mods/fh2/menu_client.zip` use the same +values. + +| Bit | Value | Checkbox label key | Menu setter | Query clause | +| --- | ---: | --- | --- | --- | +| 0 | 1 | none (no checkbox) | `setBotFilter` | `bf2_bots = 1` | +| 1 | 2 | `FILTERS_ranked` | `setRankedFilter` | `bf2_ranked = 1` | +| 2 | 4 | `FILTERS_battlerecorder` | `setBattlerecFilter` | `bf2_autorec = 1` | +| 3 | 8 | `FILTERS_battlecom` | `setBattlecomFilter` | `bf2_voip = 1` | +| 4 | 16 | `FILTERS_nopassword` | `setPasswordFilter` | `password = 0` | +| 5 | 32 | none (no checkbox) | `setDedicatedFilter` | `bf2_dedicated = 1` | +| 6 | 64 | `FILTERS_novehicles` (FH2: "Light combat mode") | `setNoVehiclesFilter` | `bf2_novehicles = 1` | +| 7 | 128 | `FILTERS_punkbuster` | `setPunkbusterFilter` | `bf2_anticheat = 1` | +| 8 | 256 | `FILTERS_populated` | `setPopulatedFilter` | `numplayers > 0` | +| 9 | 512 | `FILTERS_notfull` | `setNotfullFilter` | `numplayers < maxplayers` | +| 10 | 1024 | none (no checkbox) | `setPureFilter` | `bf2_pure = 1` | +| 11 | 2048 | `FILTERS_smallmaps` | `setSmallmapFilter` | `(bf2_mapsize = 16 or bf2_mapsize = 128)` | +| 12 | 4096 | `FILTERS_mediummaps` | `setMediummapFilter` | `bf2_mapsize = 32` | +| 13 | 8192 | `FILTERS_largemaps` | `setLargemapFilter` | `bf2_mapsize = 64` | +| 14 | 16384 | `FILTERS_sameversiononly` | `setSameVersionFilter` | `gamever = ''` | +| 15 | 32768 | `FILTERS_samemod` | `setSameMod` | `gamevariant = ''` | + +The menu sets no bits above 15. + +Examples: + +- `0`: no filters. +- `30`: Ranked, BattleRecorder, BattleComm and No password (2 + 4 + 8 + 16). +- `63616`: the retail default. PunkBuster, Small, Medium and Large maps, Same version only + and Same mod (128 + 2048 + 4096 + 8192 + 16384 + 32768). + +## How the mask is used + +- `GeneralSettings::setToggleFilters(int)` replaces the whole mask. It is the + `GeneralSettings.setToggleFilters` console method that `General.con` runs when a profile + loads, and the line `GeneralSettings` writes back when the profile is saved. +- `dice.bf2.Multiplay.getToggleFilter(mask)` returns whether any bit in `mask` is set. When the + filters page opens, the menu's `toggleFilterInit` uses it to set each checkbox. +- `dice.bf2.Multiplay.setToggleFilter(mask, on, clause)` sets or clears one bit and stores its + clause. An empty clause (or `%%`) clears the bit whatever `on` is, and removes the clause. + Each checkbox setter passes an empty clause when the box is unchecked. +- `dice.bf2.Multiplay.updateFilter()` builds the query from the stored clauses whose bit is + set, in ascending bit order. Clauses are joined with `and`. The three map-size clauses form + one group joined with `or`, in parentheses when more than one is set. The free-text filter + from `Multiplay.setFilter` is appended last. + +The implementation is in `Code/BF2/Game/GeneralSettings.h` and the `as_multiplay_*Filter` +bindings in `Code/BF2/External/gameswf/SwiffPlayer/SwiffPlayer.cpp`. + +The stored mask does not filter anything by itself. `updateFilter` only uses clauses held in +memory, and only the menu's `setToggleFilter` calls put them there. In the shipped menu those +calls come from the checkbox setters. `toggleFilterInit` sets each checkbox from the mask, +which runs the setter for that box. `toggleFilterInit` runs on the `filters` frame of the +browser sprite, so a profile's saved filters take effect in a session once the player opens +the Filters page. Bits that have no checkbox (1, 32 and 1024) are never turned into clauses +by the shipped menu. + +## Default for new profiles + +Retail BF2 1.50 hard-codes `63616` in two places: the `GeneralSettings` constructor and +`GeneralSettings::setDefaultValues`. Creating a profile calls `setDefaults()` and then saves +the profile, so every new profile's `General.con` starts with `setToggleFilters 63616`. +Existing profiles keep whatever their `General.con` holds. + +This engine uses `0` instead, so new profiles start with no filters. This is a deliberate +departure from retail behavior. The two assignments in `GeneralSettings.cpp` and the +expectations in `Code/Tests/general_settings_runtime.cpp` change together. + +The menu movie only reads and changes the mask; it never supplies a default. A mod running +the retail executable can still control the filters without engine changes: + +- **Menu.** Change `toggleFilterInit` to set every checkbox to unchecked instead of reading + the mask. Each setter then calls `setToggleFilter(mask, false, "")`, which clears the bit + and drops its clause, and the cleared mask is saved with the profile. Disabling the + checkboxes as well keeps the filters off for every profile, including ones whose + `General.con` was edited by hand. +- **Launcher.** Write `GeneralSettings.setToggleFilters 0` into each profile's `General.con` + before starting the game. A profile created in the game during that session still starts + with the executable's default until the next launch. +- **Executable patch.** In the retail BF2 1.50 executable the value is the 32-bit immediate + of two `mov dword ptr [esi+0F4h], 0F880h` instructions, one in `setDefaultValues` and one + in the constructor. Setting both immediates to `0` changes the default for new profiles + only. + +## Reading the menu ActionScript + +`Code/Tools/SwfDisasm/avm1_disasm.py` lists the ActionScript bytecode of a Flash menu movie, +with constant-pool strings resolved. It runs on Python 2.7 or 3 and needs no extra packages. + +``` +python Code/Tools/SwfDisasm/avm1_disasm.py "/mods/fh2/menu_client.zip" ^ + --member External/FlashMenu/mainMenu.swf -o mainMenu.asm +``` + +Write the output outside `Code/BF2`. To find the filter masks, search the listing for +`setToggleFilter`. Each checkbox setter pushes `r1, r2, , 3` before calling +`dice.bf2.Multiplay.setToggleFilter`. AVM1 pushes arguments last-first, so the call is +`setToggleFilter(, r2, r1)`: `r2` is the checkbox state and `r1` the clause. + +The listing marks each timeline frame with a `Frame ` line and shows its `FrameLabel`, +so frame actions can be matched to `gotoAndStop` targets. A frame's label can appear after +the frame's actions. + +The tool decodes `DoAction`, `DoInitAction` and nested sprite actions. It does not decode +button actions or clip-event actions, and it does not resolve branch targets or +`DefineFunction2` parameter registers.