extensions and runtime graph reconstruction #1370

New issue

Open

opened 2026-10-16 21:04:46 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:04:46 +00:00

Owner

Originally created by @matbrgz on GitHub (Oct 14, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/3649

Summary

Clickteam Fusion (including Multimedia Fusion 2, Clickteam Fusion 2.5, and classic Klik & Play / The Games Factory) is an enduring visual event-driven engine behind major commercial games (Five Nights at Freddy's franchise, The Escapists, Freedom Planet, Baba Is You early builds).

Clickteam applications compile their assets, objects, extensions, and event sheets into proprietary binary packages:

Standalone Windows PE executables with appended binary packs;
.mfa source project files and compiled .ccn game containers;
Embedded extension modules (.mfx DLLs);
Event tables structured as Conditions, Actions, and Events (CAE) evaluated every tick.

Currently, REA analyzes native PE executables (#3624), but cannot recover the visual event model, object qualifiers, or extension boundaries of Clickteam Fusion binaries.

This feature proposal introduces dedicated Clickteam Fusion Reverse Engineering to REA, enabling binary package unpacking, object property extraction, event sheet reconstruction, and extension mapping.

Technical Capabilities & Architecture

                                    +-----------------------------------------+
                                    | Input: Clickteam Executable (.exe) or   |
                                    |        Compiled Package (.ccn / .mfa)   |
                                    +--------------------+--------------------+
                                                         |
                         +-------------------------------+-------------------------------+
                         |                                                               |
                         v                                                               v
           +---------------------------+                                   +---------------------------+
           | Binary Container Unpacker |                                   | Frame & Object List Parser|
           | (Appended pack, Zlib chunks                                   | (Active, Backdrop, String)|
           +-------------+-------------+                                   +-------------+-------------+
                         |                                                               |
                         +-------------------------------+-------------------------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | Event Sheet & CAE Engine Inversion    |
                                     | (Conditions, Actions, Event Loops)    |
                                     +-------------------+-------------------+
                                                         |
                         +-------------------------------+-------------------------------+
                         |                                                               |
                         v                                                               v
           +---------------------------+                                   +---------------------------+
           | Extension Module Boundary |                                   | Global Data & Asset       |
           | (.mfx DLLs, Native Bridge)|                                   | Carving (Sounds, Images)  |
           +-------------+-------------+                                   +-------------+-------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | REA Evidence: Event Sheet Dossier,    |
                                     | Frame Flowchart & Object Schemas      |
                                     +---------------------------------------+

1. Package Unpacking & Header Ingestion

Executable Pack Inversion: Scan Windows PE executables for the appended Clickteam runtime pack (detecting PAME, PAMU, TARGET headers and chunk offsets from PE overlay).
Chunk Stream Parser: Parse compressed chunk streams (Zlib de-compression):
- General options, title, target frame rate, display mode (DirectX 9/11).
- Global values and global string tables.
- Binary file bank (embedded external assets).

2. Frames & Object Bank Parsing

Frame Deserialization: Extract game frames/levels: frame name, dimensions, background palette/color, virtual width/height, and frame fade transitions.
Object Types & Instances:
- Standard objects: Active Objects (animations, directions, collision boxes), Quick Backdrops, Text/String objects, Counters, Lives, Score.
- Object Qualifiers: group assignments (e.g. Bad, Good, Player, Obstacle).
- Instance layout: (x, y) coordinates, layer indices, alterable values (strings and numbers), flags.

3. Event Sheet & CAE (Condition-Action-Event) Reconstruction

Event Tree Parsing: Reconstruct Clickteam's tick-based evaluation tree:
- Conditions: Object collision tests, variable comparisons, timer checks, mouse/keyboard inputs, user-defined loops.
- Actions: Object movements, variable assignments, destroy/create instance calls, sound playback, frame transitions.
- Events: Event lines, OR/AND logical groupings, immediate events vs. queued events.
Human-Readable Export: Export event sheets as structured, readable pseudocode rules or JSON rule graphs.

4. Extension Modules (.mfx) & Native C++ Integration

Extension Carving: Extract embedded .mfx extension dynamic libraries (e.g. Lacewing networking, Surface object, Blowfish encryption, Steamworks).
Native Symbol Resolution: Correlate extension action/condition IDs with native exported functions in REA's Ghidra/Rizin providers.

Acceptance Criteria

Introduce analyze_clickteam_package in REA CLI and MCP contracts, accepting .exe, .ccn, and .mfa files.
Unpack synthetic Clickteam Fusion test packages without memory faults.
Extract frames, active objects, and alterable values into structured JSON evidence.
Reconstruct condition-action event lines into readable pseudocode.
Identify embedded .mfx extensions and catalog their action/condition interface IDs.

#3624 [Feature] Native C++ semantic reconstruction
#3621 [Feature] Unknown binary file-format inference
#3632 [Feature] GameMaker reverse engineering: data.win, GML bytecode

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3649 [![Type: Feature](https://img.shields.io/badge/type-feature-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Domain: Game & Engine RE](https://img.shields.io/badge/domain-game_&_engine_RE-green.svg?style=flat-square)](https://github.com/morluto/rea) [![Status: Proposed](https://img.shields.io/badge/status-proposed-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Ecosystem: REA](https://img.shields.io/badge/ecosystem-morluto%2Frea-8A2BE2.svg?style=flat-square)](https://github.com/morluto/rea) ## Summary Clickteam Fusion (including Multimedia Fusion 2, Clickteam Fusion 2.5, and classic Klik & Play / The Games Factory) is an enduring visual event-driven engine behind major commercial games (*Five Nights at Freddy's* franchise, *The Escapists*, *Freedom Planet*, *Baba Is You* early builds). Clickteam applications compile their assets, objects, extensions, and event sheets into proprietary binary packages: - Standalone Windows PE executables with appended binary packs; - `.mfa` source project files and compiled `.ccn` game containers; - Embedded extension modules (`.mfx` DLLs); - Event tables structured as Conditions, Actions, and Events (`CAE`) evaluated every tick. Currently, REA analyzes native PE executables (#3624), but cannot recover the visual event model, object qualifiers, or extension boundaries of Clickteam Fusion binaries. This feature proposal introduces dedicated **Clickteam Fusion Reverse Engineering** to REA, enabling binary package unpacking, object property extraction, event sheet reconstruction, and extension mapping. --- ## Technical Capabilities & Architecture ``` +-----------------------------------------+ | Input: Clickteam Executable (.exe) or | | Compiled Package (.ccn / .mfa) | +--------------------+--------------------+ | +-------------------------------+-------------------------------+ | | v v +---------------------------+ +---------------------------+ | Binary Container Unpacker | | Frame & Object List Parser| | (Appended pack, Zlib chunks | (Active, Backdrop, String)| +-------------+-------------+ +-------------+-------------+ | | +-------------------------------+-------------------------------+ | v +---------------------------------------+ | Event Sheet & CAE Engine Inversion | | (Conditions, Actions, Event Loops) | +-------------------+-------------------+ | +-------------------------------+-------------------------------+ | | v v +---------------------------+ +---------------------------+ | Extension Module Boundary | | Global Data & Asset | | (.mfx DLLs, Native Bridge)| | Carving (Sounds, Images) | +-------------+-------------+ +-------------+-------------+ | v +---------------------------------------+ | REA Evidence: Event Sheet Dossier, | | Frame Flowchart & Object Schemas | +---------------------------------------+ ``` ### 1. Package Unpacking & Header Ingestion - **Executable Pack Inversion:** Scan Windows PE executables for the appended Clickteam runtime pack (detecting `PAME`, `PAMU`, `TARGET` headers and chunk offsets from PE overlay). - **Chunk Stream Parser:** Parse compressed chunk streams (Zlib de-compression): - General options, title, target frame rate, display mode (DirectX 9/11). - Global values and global string tables. - Binary file bank (embedded external assets). ### 2. Frames & Object Bank Parsing - **Frame Deserialization:** Extract game frames/levels: frame name, dimensions, background palette/color, virtual width/height, and frame fade transitions. - **Object Types & Instances:** - Standard objects: Active Objects (animations, directions, collision boxes), Quick Backdrops, Text/String objects, Counters, Lives, Score. - Object Qualifiers: group assignments (e.g. `Bad`, `Good`, `Player`, `Obstacle`). - Instance layout: $(x, y)$ coordinates, layer indices, alterable values (strings and numbers), flags. ### 3. Event Sheet & CAE (Condition-Action-Event) Reconstruction - **Event Tree Parsing:** Reconstruct Clickteam's tick-based evaluation tree: - **Conditions:** Object collision tests, variable comparisons, timer checks, mouse/keyboard inputs, user-defined loops. - **Actions:** Object movements, variable assignments, destroy/create instance calls, sound playback, frame transitions. - **Events:** Event lines, OR/AND logical groupings, immediate events vs. queued events. - **Human-Readable Export:** Export event sheets as structured, readable pseudocode rules or JSON rule graphs. ### 4. Extension Modules (.mfx) & Native C++ Integration - **Extension Carving:** Extract embedded `.mfx` extension dynamic libraries (e.g. Lacewing networking, Surface object, Blowfish encryption, Steamworks). - **Native Symbol Resolution:** Correlate extension action/condition IDs with native exported functions in REA's Ghidra/Rizin providers. --- ## Acceptance Criteria 1. Introduce `analyze_clickteam_package` in REA CLI and MCP contracts, accepting `.exe`, `.ccn`, and `.mfa` files. 2. Unpack synthetic Clickteam Fusion test packages without memory faults. 3. Extract frames, active objects, and alterable values into structured JSON evidence. 4. Reconstruct condition-action event lines into readable pseudocode. 5. Identify embedded `.mfx` extensions and catalog their action/condition interface IDs. --- ## Related - #3624 [Feature] Native C++ semantic reconstruction - #3621 [Feature] Unknown binary file-format inference - #3632 [Feature] GameMaker reverse engineering: data.win, GML bytecode

bsakaguchi referenced this issue

2026-10-17 21:01:32 +00:00

[GH-ISSUE #2383] [Tracker] Audit analysis and debugging coverage for the TIOBE top 100 languages (October 2026) #794

bsakaguchi referenced this issue

2026-10-17 21:10:48 +00:00

[PR #1370] [MERGED] perf(javascript): validate the version change graph once #2833

bsakaguchi referenced this issue

2026-10-17 21:11:23 +00:00

[PR #1434] [MERGED] perf(javascript): index change-graph nodes once per comparison #2884

bsakaguchi referenced this issue

2026-10-17 21:11:36 +00:00

[PR #1458] [MERGED] perf(javascript): derive the application graph ID once #2900