From 01c2344d0219c142dd7ec157c00bd2fd1f3724b5 Mon Sep 17 00:00:00 2001 From: Axle1975 Date: Sat, 20 Jun 2026 14:42:39 +1000 Subject: [PATCH] Add tdraw.dll, tdraw.txt and LICENSE --- .gitattributes | 1 + LICENSE | 79 +++++++ tdraw.dll | 3 + tdraw.txt | 580 +++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 663 insertions(+) create mode 100644 LICENSE create mode 100644 tdraw.dll create mode 100644 tdraw.txt diff --git a/.gitattributes b/.gitattributes index e78561e..ba702dd 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,3 +1,4 @@ TADEMO.UFO filter=lfs diff=lfs merge=lfs -text online.dll filter=lfs diff=lfs merge=lfs -text rev31.gp3 filter=lfs diff=lfs merge=lfs -text +tdraw.dll filter=lfs diff=lfs merge=lfs -text diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..41838b3 --- /dev/null +++ b/LICENSE @@ -0,0 +1,79 @@ +# TA Demo Recorder and Community Patch + +## LICENSE + +### TA Community Patch (original filename: tdraw.dll; source directory: src/DDRaw) + +The MIT License (MIT) + +Copyright (c) 2023 Axle1975, FunkyFr3sh +Copyright (c) 2019 Xpoy +Copyright (c) 2003 SJ, Yeha + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +### TA Demo Recorder (original filename: tplayx.dll; source directory: src/Recorder) + +The MIT License (MIT) + +Copyright (c) 2015 Rime +Copyright (c) 2003 SJ, Yeha + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +### TA Demo Replayer (original filename: SERVER.EXE, source directory: src/Server) + +The MIT License (MIT) + +Copyright (c) 2015 Chaos +Copyright (c) 2003 Fnordia + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/tdraw.dll b/tdraw.dll new file mode 100644 index 0000000..817d9ba --- /dev/null +++ b/tdraw.dll @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b60b173afb7b84ef2a7603051ad673e5991ad9379d58cdbd59ff54e82fd2b084 +size 865280 diff --git a/tdraw.txt b/tdraw.txt new file mode 100644 index 0000000..46da9e2 --- /dev/null +++ b/tdraw.txt @@ -0,0 +1,580 @@ +WHAT IS THIS + +tdraw.dll is an upgrade for Total Annihilation. It patches the game to fix many bugs and add many features. +It is an integral component of the TA Community Patch, the other parts being tplayx.dll (the recorder) and server.exe (the replayer). + +tdraw.dll has a long provenance dating back to the work of SY_Yeha, who introduced whiteboard markers and the TA Hook and new hotkeys to TA. +Later work by Xpoy extended hotkey support, added new shortcut commands, uni-code font support, megamap, weapon-id crack (not present in current release) and porting music patch from GOG version, +and later support was provided by Rime. + +The present release includes contributions from Axle and FunkyFresh, and owes a debt to TAG_Venom for extensive testing and critical feeback, and to Gamma and Wotan for further testing and feature suggestions. + + +CONFIGURATIONS + +The release .zip files are annotated with a build configuration tag: "tdraw-.zip". The various configurations are: + * tdraw-full.zip: all features enabled + * tdraw-escalation.zip: built for TA:Escalation. disables the following features + - mex snap + - that is all + * tdraw-minimal.zip: disables the following features + - mex/wreck snap + - options for construction units to stay put when guarding + - options for construction units to only reclaim or onlt assist while patrolling + - auto kickout construction units that are blocking another builder + - weather report at top of screen + - sync wind speed between players + - map DT's always visible. + + +INSTALLATION + +Drop tdraw.dll into your TA directory. +Ensure the following files are also present in your TA directory: +- ddraw.dll (available from https://github.com/FunkyFr3sh/cnc-ddraw) +- totala.ini + +You may need to rename totala.ini and tdraw.dll to whatever your mod is using. See below for reference. For other mods, please consult with the mod maintainers. + + ini file dll file +Beta patch 3.9.02 TA.ini tdraw.dll +Escalation 9.9.6 TAESC.ini taesc.dll +Mayhem 10.9.2 Settings.ini mdraw.dll +ProTA 4.6 ProTA.ini tdraw.dll +Zero Alpha5-060322 tazero.ini zdraw.dll + + +NEW FEATURES IN BRIEF: + +*2026.6.8 +- bugfix for VoteReject - prevent local user from rejecting himself + +*2026.6.3 +- add "nottounderwater" flag for weapons (see NEW FEATURES IN DETAIL) +- fix bug potentially being the root cause of since-year-1997 intermittent black screen on join games +- better quality megamap render + +*2026.5.28 +- Fix construction units intermittently trying to sit within the footprint of rotated structures before building them + +*2026.5.15 +- Fix intermittent 6x8 staircase yardmap on south-facing rotatable factories +- New "PreviewObject3D=" unit key to override the 3DO model used for the nanoframe ghost preview (see NEW FEATURES IN DETAIL) + +*2026.5.9 +- Lag-switch mitigation: detects and freezes local simulation when network goes dark +- Vote-to-reject system for in-progress multiplayer games (see NEW FEATURES IN DETAIL) +- add "nottoair" flag for weapons (see NEW FEATURES IN DETAIL) +- add "surfacefire" flag for weapons (see NEW FEATURES IN DETAIL) +- +autoteam bugfix for occasional players stranded by themselves +- Diagnostic logging for crashes 004cbed5 and 0049cf19 +- Building rotation: press '/' (configurable) to cycle the build cursor + facing for buildings whose FBI permits it (see NEW FEATURES IN DETAIL) +- Nanoframe ghost preview at the build cursor (see NEW FEATURES IN DETAIL) +- Fix for ctrl-z (and ctrl-a / ctrl-b / ctrl-c) silently truncating selections for unit ids >= 512 +- Export engine-backed player elimination status to gpgnet4ta via shared memory, + so games where a commander dies but play continues are reported with the correct outcome + +*2026.2.17 - Fix false trigger on version check +*2026.2.10 - Minor adjustment to diagnostic crash detection ("ERROR: dstRect out of bounds", allow CopyScreenContext all the way to the edge of destination context) +*2026.2.7 - Disable AUTOTEAM, RANDOMTEAM and CRCREPORT buttons for non-host players +*2026.2.5 - Add support for AUTOTEAM, RANDOMTEAM and CRCREPORT buttons in battleroom (guis/lounge2.gui) +*2026.2.2 - Custom ctrl-f2 menu skin for escalation +*2026.1.29 - Create seperate builds for full-featured (tdraw-full.zip), escalation (tdraw-escalation.zip), and minimal (tdraw-minimal.zip) feature sets. +*2025.12.13 - Add diagnostics for crash at 004cbed5 +*2025.12.6 - Fix crash when game installed in a long path (eg C:\Program Files (x86)\Steam\steamapps\common\Total Annihilation\PROTA) +*2025.11.26 - New keys for unit definitions (units/*.fbi) to customise per-unit veterancy +*2025.8.29 - Bugfix for multithreaded version/cheat check +*2025.8.19 - Auto kickout of units under build order is now strictly only for own units (previously allowed kickout anyone's units if cheats enabled) +*2025.8.1 - Set build square preview to yellow if user can build there but it contains a unit that will be kicked out + +*2025.7.12 +- Allow user to queue build orders underneath their own mobile units; and auto kickout of units that are under a build order +- Mod developers can opt-in to "Improved behaviour of con units". + Modifies what construction units that are guarding factories do after completing each unit: either stay put; cavedog; or scatter. + Set byte at TotalA.exe:0x101f1f to 0x00 to disable the feature (default) or 0x01 to enable the feature. + Note that if one player's 0x101f1f setting doesn't match that of other players, an in-game cheat warning will be triggered. + Once enabled, see ctrl-f2 menu for related user configurable options. +- Fix bug with erroneous game results reported to TAF when using in-game +autoteam +- With fixed position, start positions are assigned in order given by TAF auto balance + so that players are positioned opposite an opponent of similar skill +- Fixed bugs with player placement in 2v2+ games on maps with neutral units +- Push anticheat hashing functions into background threads so as to reduce in-game slowdown experienced by some users + +*v2025.5.18 +- Improved behaviour of con units when guarding a factory - they stay put after finishing a build + +*v2025.4.24 +- Fix crash on parsing spawned unit initial commands - its now possible to copy-paste mission scripts from campaign +- Log cheat warnings to tdrawlog.txt for offline analysis +- Fix for non functional perm-los sonar patch (which otherwise requires watcher's com to be in top-left of map to work) + +*v2024.12.5 +- Fix crash on print-screen (and presumably many other related crashes) + +*v2024.12.3 +- Fix crash on +logo +- Fix rare intermitent crash on adding / moving / deleting whiteboard markers + +*v2024.10.27 +- Ability to create multiplayer/skirmish maps with neutral units and/or additional per-player spawn units +- Add a controls to hide/minimise the allies resource bar +- Make the allies resource bar actually work with ctrl-f2 setting "background=None" +- Fix incorrect player logo colour for "new marker added" messages +- Player the "Mission Complete" sound upon winning a multiplayer/skirmish game +- Fix bug causing "unit limit reached" in between single player missions +- Remove shared metal/energy from player "totals" +- Get TAHook to use the click-snapped start position +- Increase size capacity of whiteboard marker messages +- Fix for 10 player (and other) VerCheck false positives +- Support for watching all 10 players in 10 player replays (pending a corresponding TAF update to activate it) + + +*v2024.3.31 and prior +- Set start positions based on battleroom teams (or alliances) +- Repair battleroom teams icons so they can be used to create teams before to launching +- Add +autoteam battleroom and in-game commands to automatically assign teams +- Add +randomteam battleroom command to automatically assign random teams +- Add .exereport battleroom command to report CRC32 of each player's totala.exe +- Add .tdreport battleroom command to report CRC32 of each player's tdraw.dll (may be a different filename depending on mod) +- Add .tpreport battleroom command to report CRC32 of each player's tplayx.dll (may be a different filename depending on mod) +- Add .gp3report battleroom command to report CRC32 of each player's rev31.gp3 (may be a different filename depending on mod) +- Add .crcreport battleroom command to report fingerprints of each player's totala.exe, tdraw.dll, tplayx.dll and rev31.gp3 file all at once +- ClickSnap to snap to nearest mex, geo or reclaimable feature +- Add ability to drag queued orders around the map +- Con units patrol behaviour - hold position: reclaim only +- Fix the "ghost com" bug (remote commanders appear in top left of map during first 50sec of game) +- Fix the "units exploding in factories" bug by holding back recycling of deceased units' IDs for 5 seconds +- Option to render DTs and fortwalls that belong to the map (not built by a player) +- Supress "qqqqqq" whiteboard marker lables when "q" is used as the whiteboard key +- Show clock and weather report (wind and tidal strength) on top resource panel +- Sync wind speed across all players +- Set default resolution on new installs to 1024x768 (.ini setting "DisplayModeMinHeight768 = TRUE/FALSE") +- Disable relay of F11 chatmacro text to other players +- Enable start button in multiplayer lobby if only one player + AI are present +- Add +noshake and .ready buttons to sharing menu +- Add .autopause button to battleroom screen +- Change whiteboard, mappos and resource indicator colours in response to +logo commands +- Prevent +logo commands from affecting other players +- Ctrl-B doesn't select aircraft carriers +- Ctrl-F centres view on selected factory +- Ctrl-S works correctly with mobile-units-can-build-mobile-units hack +- Set +lostype as a cheatcode (not available unless cheats enabled) +- Look for ddraw.dll in current working directory as backend, or failing that use system ddraw.dll +- Use the same .ini file as TotalA.exe +- Use the same registry path as TotalA.exe +- Add FPS counter to megamap, increase megamap FPS +- Fix blue background on scoreboard +- Grey background on mega map to distinguish from unmapped area +- Prevent Ctrl-F2 dialog and allies resource bar from moving off screen +- Improve responsiveness of whiteboard marker movements sent to remote players +- Render cursor while in megamap +- Fix crash when removing markers +- Fix crash on simultaneous whiteboard marker move and delete +- Fix rare crash on TA Hook line drawing +- Radar and sonar jammers no longer jam your own radar and sonar in >3 player multiplayer +- Use CTRL_F and CTRL_B unit category tags for ctrl+f and ctrl+b hotkeys in preference to heuristics +- Change ctrl+s to use CTRL_W and NOTAIR/NAIR categories so as not to select jammers etc + +NEW FEATURES IN DETAIL: + +- Start positions + + Start positions are now assigned based on battleroom teams/alliances. + With fixed positions, host and their team are assigned the odd positions in the order that they joined the lobby. + With random positions, host and their team are randomly assigned the even or odd positions, and they are assigned in random order. + + The Teams icons now function correctly, so they can be used to arrange teams in the battleroom if desired. + This is optional, it is perfectly fine to arrange teams by creating alliances too. + +- Autoteam + + In the battleroom, host can type "+autoteam" to have teams assigned automatically. + These teams will then determine the start positions as described above. + + If launched from TAF, the battleroom +autoteam will assign autobalanced teams based on the player rating. + Otherwise teams are assigned randomly. + The +randomteam command is available to use should you prefer random teams over autobalanced teams. + + Alternatively, if host types "+autoteam" in-game, alliances are created based on actual start positions. + + For more than 2 teams, host can type eg "+autoteam 3" to create the desired number of teams. + +- MexSnap and WreckSnap + + This patch includes ability to snap mexes and geos to the nearest metal or geo patch (MexSnap), + and to snap reclaim commands to the nearest reclaim (WreckSnap). + + While holding down shift, press q and e alternately to switch between building mexes and reclaiming features. + + If Mex/WreckSnap is temporarily interfering with your wishes, + you can hold down alt to override it. + The override key can be configured in the ctrl-f2 options menu. + + The Mex/WreckSnap radii can also be configured independently via the ctrl-f2 options menu. + Press ctrl-f2, click on the "MexSnap" or "WreckSnap" field and press a number 0 to 9. + 0 disables the Mex/WreckSnap and a larger radius results in snapping to features further away. + + Note that Mex/WreckSnap is disabled by default. + It needs to be enabled by the mod maintainer. + If your Mex/WreckSnap radius shows as "NA" in the ctrl-f2 menu, + it is likely that Mex/WreckSnap hasn't been enabled by your mod maintainer. + +- Move Queued Orders + + After queueing a build order or a move order, + you can later move them around by selecting the unit + and left mouse dragging the order to a new position. + +- Construction Units Patrol Behaviour + + Patrol behaviour of contructions units is modified depending on their movement orders: + + Hold Position: your construction units will only look for reclaim + Maneuvre/roam: your construction units will both look for reclaim and for units that need repair or assist + + Mash the 'v' key to get the desired movement order and then set a patrol route. + +- Neutral unit and/or per-player additional unit spawn + + To enable this feature add a "[units]" section under the "[Schema 0]" section of your map's .ota file. eg + + [Schema 0] + { + .... + [units] + { + [unit0] + { + Unitname=ARMHLT; + Ident=; + XPos=3164; + YPos=0; + ZPos=2250; + Player=11; + HealthPercentage=100; + } + [unit0] + { + Unitname=ARMPEEP; + Ident=; + XPos=268; + YPos=0; + ZPos=384; + Player=1; + HealthPercentage=100; + CreationCountdown=30; + InitialMission=p 1750 1828; + } + } + + These additional units will spawn in for skirmish/multiplayer. + + The "Player" key in the .ota file refers to the map position 1..10. + Whichever player is spawned into these positions will receive ownership of the respective units. + + You can set Player=11. If any Player=11 units are defined, then the last player (eg the 6th in a 3v3) + receives ownership of the Player=11 units as long as they are an AI. He does not receive ownership of any other units. + + If a player receives any units by this mechanism, they won't receive a commander. + If you want the player to have a commander, + then either don't define any units for that position, + or include a commander unit in the list of units. + + The required fields for each unit are UnitName, XPos, ZPos and Player. + YPos and HealthPercentage are ignored. + Optional CreationCountdown is in seconds and InitialMission works. + Optional Ident makes it possible to refer to the unit in InitialMission of another unit. + You'll have to look at eg totala4.hpi/maps/*.OTA for examples of InitialMission scripts to copy. + +- Vote-to-Reject + + When a player is to be rejected during an in-progress multiplayer game, the rejection must now be + approved by a majority vote rather than taking effect immediately. + + Manual reject (initiated via Tab → Control → player → reject prompt): + The proposer's YES is counted automatically. All other non-target players are shown a vote dialog + and may click YES or NO. The reject passes if at least 2/3 of non-target active players vote YES + (minimum 1). If the target has a teammate, that teammate must vote YES for the reject to pass. + If the vote fails by a NO majority it is cancelled immediately; otherwise the vote times out after + 60 seconds with no effect and a 90-second cooldown is imposed before another vote can be proposed. + + Timeout reject (triggered automatically when a player stops responding for 30 seconds): + All players are shown the vote dialog. The reject passes if at least 2 players vote YES + (or just 1 in a 2-player game), provided at least one ally of the timed-out player has voted YES. + If a NO majority makes the threshold unreachable, voting closes early and the player is + automatically rejected when the 90-second vote timer expires. + + The vote dialog: + Each active vote appears as a row in an overlay dialog at the top-centre of the screen. + Each row shows the vote subject ("X has timed out - vote to reject?" or + "VOTE: X wants to reject Y"), the current tally (Ny/Nn/total, countdown), and YES / NO buttons. + Clicking YES or NO casts your vote and broadcasts it to all other players. + + For timeout votes where the local player is an ally of the timed-out player, a ".take" button + is also shown. Clicking it broadcasts the chat message ".take", which the recorder (tplayx.dll) + interprets as the player taking over the timed-out player's units. Once the recorder confirms + the take, the corresponding vote is automatically cancelled. + +- Per-Unit Veterancy Customization + + This patch introduces new optional keys for unit definition files (units/*.fbi) + that allow you to customize veterancy behavior for individual units. + + Example + + [UNITINFO] + { + UnitName=ARMMART; + ... + VeterancyThresholds=6 12 18 24 30; // OTA default: 5 10 15 20 25 + VeterancyAccuracyBuffRate=3; // OTA default: 12 + } + + New Keys + + - VeterancyThresholds: + Sets the number of kills required to reach each veterancy level (VetLevel). + Example: "6 12 18 24 30" means: + - 6 kills for VetLevel 1 + - 12 kills for VetLevel 2 + - 18 kills for VetLevel 3 + - etc. + OTA's default thresholds are "5 10 15 20 25". + + - VeterancyAccuracyBuffRate: + Controls how quickly a unit’s weapon accuracy improves with kills, independently of veterancy levels. + - Accuracy starts at a factor of 1 with 0 kills. + - This factor increases by +1 every VeterancyAccuracyBuffRate kills. + - Formula: accuracyFactor = 1 + floor(kills / VeterancyAccuracyBuffRate) + - OTA’s default rate is 12. + - Set to zero to disable accuracy buff altogether + + Veterancy Effects (Unchanged) + + This patch does NOT change what veterancy levels do, only how they are earned. + For reference, each VetLevel in OTA gives: + + - Capture cost: +10% worker time needed to capture the unit + - Damage taken: -4% damage received + - Damage dealt: +6% damage dealt + - Target tracking: improved weapon target tracking (effect uncertain) + - Reload time: -6% weapon reload time + - Accuracy buff: improved firing accuracy (randomness reduced by an increasing factor) + + Note: Reload time also appears to be affected by the unit’s health. + + Veterancy Limits + + OTA limits: + - Capture cost: no limit + - Damage taken: up to 5 levels + - Damage dealt: up to 5 levels + - Target tracking: up to 1 level + - Reload time: up to 5 levels + - Accuracy buff: no limit + + With this patch: + - Capture cost: no limit + Beyond the last specified threshold, kill requirements are extrapolated linearly from the last two thresholds. + - Damage taken: up to 25 levels or the number of VeterancyThresholds, whichever is lower + - Damage dealt: up to the number of VeterancyThresholds + - Target tracking: up to 1 level + - Reload time: up to 16 levels or the number of VeterancyThresholds, whichever is lower + - Accuracy buff: no limit + +- Weapon TDF flags: nottoair, nottounderwater and surfacefire + + Two new optional keys for weapon definition files (weapons/*.tdf) give mod developers + finer control over which unit types a weapon can target. + + nottoair=1 + The weapon cannot target or fire at flying units (units with an airborne movement state). + Useful for weapons that are physically implausible against air targets, such as depth charges + or large ballistic artillery. + + Example: + + [DEPTH_CHARGE] + { + ... + nottoair=1; + } + + nottounderwater=1 + The weapon cannot target or fire at fully-submerged units (a target whose top is at or below + sea level, such as a dived submarine). Ordinary weapons already cannot reach underwater + targets; this flag is meant for waterweapon=1 weapons, letting them hit surface ships while + leaving submerged units to torpedoes and depth charges. It is the underwater mirror of + nottoair. + + Example: + + [NAVAL_GUN] + { + ... + waterweapon=1; + nottounderwater=1; + } + + surfacefire=1 + Used together with waterweapon=1. Normally a water weapon can only target submarines and + other units that are at or below sea level. With surfacefire=1 the weapon can also target + surface units above sea level, such as hovercraft or land units near the shoreline. + Both auto-aim and manual targeting are affected. + + Example: + + [TORPEDO_SURFACE] + { + ... + waterweapon=1; + surfacefire=1; + } + +- Building rotation + + While a building is selected for placement, press '/' to cycle through the + facings the unit allows. Shift may be held while pressing '/' so you can + rotate without lifting the line-build modifier. Most buildings only allow + their default facing, in which case the key does nothing. The rotate key + can be reassigned in the ctrl-f2 menu. + + Alternatively, hold the snap-override key (default Alt — also configurable + in ctrl-f2) and scroll the mouse wheel: forward = counter-clockwise, back + = clockwise. This leaves plain mouse-wheel free for the megamap. + + A third option is built into the build menu itself. Each rotatable + structure button has a small overlay marker on each cardinal it can + face (S = bottom edge, E = right, N = top, W = left). Click the + button on the corresponding edge to enter placement mode with that + rotation already chosen — clicks in the centre of the button select + the unit normally and keep the previously chosen rotation. Tick or + un-tick "Build menu rotation overlay" in the ctrl-f2 menu to enable + or disable the overlay (when off, the build menu is stock vanilla + and clicks behave as if it were never installed). + + Mod authors can replace the built-in chevron art by dropping a 4- + frame GAF at anims/buildrotate.gaf beside their other animations. + Frames are interpreted in the order S, E, N, W (matching the + rotation index), and each frame's hotspot is anchored just inside + the cardinal margin band of the build button so the artwork sits + cleanly inside the button rather than straddling the edge. An + optional second file anims/buildrotateclick.gaf (also 4 frames in + the same order) is blitted in place of the idle GAF for the brief + click-feedback flash; if absent, no flash is rendered (mods opting + into a custom GAF need to ship the companion click GAF themselves + if they want one). When neither GAF loads the built-in chevrons + are used. A reference generator and example .gaf files live under + tools/make_buildrotate_gaf.py in the source tree. + + Mod developers opt-in per unit by adding a "Rotations=" key to the + [UNITINFO] section of the FBI listing the cardinal letters they want + to allow, e.g. + + [UNITINFO] + { + ... + Rotations=SENW; + } + + Limitation: a few mods script their Create() function to forcibly TURN + the unit body (e.g. so structures face the centre of the map). Such + scripts run after the build cursor's rotation is applied and overwrite + it, so the Rotations= key has no visible effect on those units. + +- Nanoframe ghost preview + + A small green animated preview of the building you're about to place + is drawn inside the build rectangle. It rotates in step with the + rotate-build key, and disappears on red (can't-build) squares. When + shift-line / shift-row building, the preview is shown at every + rectangle in the row. + + Mod authors with upgrade-style units (where the 3DO model contains + both the basic and upgraded geometry, and the COB script controls + visibility at runtime) can list the pieces that should appear in the + preview by adding a "PreviewPieces=" key to [UNITINFO]: + + [UNITINFO] + { + ... + PreviewPieces=base, turret, sleeve, barrel, cover; + } + + Names are matched case-insensitively against 3DO piece names; comma, + space, or semicolon may be used as separators. When the key is set, + ONLY listed pieces are rendered. When the key is omitted (the usual + case), every piece is rendered minus a small hardcoded set of + cosmetic / firing-effect names (flare, flash, muzzle, fire, flame, + wake). + + Per-rotation overrides are also available — useful when the visible + pieces should differ by facing. Use any of: + + PreviewPiecesS=... facing south (rotation 0) + PreviewPiecesE=... facing east (rotation 1) + PreviewPiecesN=... facing north (rotation 2) + PreviewPiecesW=... facing west (rotation 3) + + Lookup order for the active rotation: + 1. PreviewPieces= if set (non-empty), uses ONLY that list. + 2. PreviewPieces= the default for every rotation. + 3. neither set every piece minus the ephemeral filter. + + For units whose Create() script auto-rotates the structure toward + the nearest enemy Commander, the preview can be made to face the + same direction — preventing the jarring snap when the build commits + — by adding: + + [UNITINFO] + { + ... + PreviewFaceOpponent=1; + } + + At each preview frame we find the nearest enemy commander to the + build cursor (each enemy player's first unit slot, which is the + commander in all but pathological cases), and snap the line from + the cursor to that commander to the nearest cardinal (S / E / N / + W). PreviewFaceOpponent overrides the Rotations= restriction — + setting this key is the author's explicit signal that the unit's + heading is script-driven, so the preview must face whichever + cardinal the script will pick regardless of what Rotations= permits + the player to cycle through. + + To avoid leaking enemy positions through fog-of-war scanning, the + override only applies when the build cursor is within the actual + builddistance of one of the local player's selected, completed + construction units (each builder gets its own threshold from its + FBI builddistance=). Outside that radius the preview falls back to + the player's rotate-build selection — same as if PreviewFaceOpponent + were unset. + + Falls back to the player's rotate-build selection in single-player + or any case where no enemy commander can be found (e.g. all enemies + dead). + + Mod authors who want the preview to display a completely different + model than the unit's actual Object3D= (e.g. a simplified silhouette, + or the upgraded form of a unit whose 3DO bundles multiple variants) + can name an alternative 3DO with a "PreviewObject3D=" key: + + [UNITINFO] + { + ... + PreviewObject3D=corarmvp_preview; + } + + The value is a 3DO base name (no extension); the file is loaded from + the HPI archive at objects3d/.3DO on first use and cached + for the rest of the game session. All other preview FBI keys + (PreviewPieces, PreviewFaceOpponent, etc.) apply to this overridden + model — piece-name whitelists are matched against the OVERRIDE 3DO's + piece names, not the unit's real one. + + If the named 3DO can't be found in the HPI, a warning is logged to + tdrawlog.txt and the preview falls back to the unit's real model; + no other behaviour is affected. + +