From 02f2dd540061e19a5d3f1de32d081548251b49b7 Mon Sep 17 00:00:00 2001 From: Florian Kaiser Date: Tue, 29 Apr 2025 13:29:07 +0200 Subject: [PATCH] Add DOCUMENTATION.md --- DOCUMENTATION.md | 186 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 DOCUMENTATION.md diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md new file mode 100644 index 00000000..20763f3d --- /dev/null +++ b/DOCUMENTATION.md @@ -0,0 +1,186 @@ +# Documentation + +## Nomenclature +- **Script**: SI File (it appears they wanted to use SI much more as actual scripts, but ended up hard-coding almost everything) +- **Action**: Mostly media file inside SI + +## Classes + +### MxAtom +Key (string) / Value (U16) pair. + +Inc() +Dec() + +### MxAtomId +String with lookup method (upper case/lower case/exact). Used for IDs. + +MxOmni holds an AtomSet that contains MxAtoms for every MxAtom ID created + a counter of how many instances exists. + +### MxString +Typical string class with utility functions. + +### MxCore +Virtual base class. + +Tickle() +Notifiy(MyParam) +GetId() +ClassName() + +IsA() +Checks ALL parents. + +### MxDSObject : MxCore +Base Object for extracted objects from SI files. + +Adds AtomId, ObjectId, Type, Flags, ObjectName and SourceName as well as a Deserialize method. + +Deserializes SourceName and ObjectName. It also saves the flags provided as a param. + +Also provides DeserializeDSObjectDispatch which deserializes an MxOb chunk into the corresponding MxDSObject child. + +### MxDSAction : MxDSObject +Deserializes Flags (ignores param), StartTime, Duration, LoopCount, Location (Vec3), Direction (Vec3) and Up (Vec3). + +Also if extra is available it appends it to ExtraData. + +### MxDSMediaAction : MxDSAction +Deserializes MediaSrcPath, two U32 into an unknown struct, FramesPerSecond, MediaFormat, PaletteManagement, SustainTime. + +### MxDSMultiAction : MxDSAction +Deserializes multiple chunks? into MxDSActions using DeserializeDSObjectDispatch + +### MxDSParallelAction : MxDSMultiAction +Just a rename from MxDSMultiAction. + +### MxDSSelectAction : MxDSParallelAction +Deserializes Unknown0x9c, checks if it starts with "RANDOM_" and if so, parses the number after "RANDOM_", gets a number from 0 to number. If not reads a string and saves it in the VariableTable. + +Then reads a list of strings (presumably numbers) into a list. Then reads the same number of chunks into objects (Actions), chooses nth one where N is the index of the string that equals to the random number. + +### MxDSSound : MxDSMediaAction +Deserializes a volume. + +### MxVariableTable : MxHashTable +MxOmni holds a VariableTable that is just a key/value store string/string. + +### LegoBuildingManager : MxCore + +#### CreateBuilding() + +### MxEntity : MxCore +Adds EntityId (S32) and AtomID (MxAtomId). + +### LegoEntity : MxEntity +Adds WorldDirection, WorldUp, WorldPostion, WorldSpeed, ROI, CameraFlag, Flags, + +Virtual methods: +ClickSound(bool) +ClickAnimation() +SwitchVariant() +SwitchSound() +SwitchMove() +SwitchColor(LegoROI*) +SwitchMood() + +#### ParseAction(char*) +Parses a string like ""ACTION:; ; " + +If action is not 7 (e_exit), it stores the filename into m_siFile, and if the action is not 6 (e_run) it stores the ID into m_targetEntityId. + +### ROI +Has LODlist (a list of LODObject), Visibility and ROIList (a list of ROI-pointers, via CompoundObject). + +Provides (deleted) functions for world velocity, bounding box and bounding sphere. + +### OrientableROI : ROI +Adds Local2World 4x4-matrix, WorldBoundingBox (and WorldBoundingSphere), WorldVelocity, ParentROI (another OrientableROI). +Also has an unknown bounding box and u32. The u32 can be enabled/disabled which either sets bit 1 and 3 or clears only bit 1. + +WorldUp, WorldDirection and WorldPosition are within `local2world`'s second, third and forth row. + +### ViewROI : OrientableROI +Adds Geometry saved withing a Tgl::Group and Unknown int. + +Uses the lod list with its own type ViewLODList (ref counted). + +### LegoROI : ViewROI +Adds Name, Entity, BoundingSphere. Provides functions to color/texture every lod (also based on global handlers). + +### LegoWorld : LegoEntity + +#### PlaceActor(...) +Goes through all controllers in m_controllerList and calls PlaceActor(). + +### LegoActor : LegoEntity +Adds Controller (LegoPathController*), Boundary, CollideBox, LastTime, ActorTime +Has UserNavFlag which presumably defines if user controls this character. Also has an ActorState: + +``` +enum ActorState { + // States + c_initial = 0, + c_one = 1, + c_two = 2, + c_three = 3, + c_disabled = 4` + c_maxState = 255, + + // Flags + c_noCollide = 0x100 +} +``` + +UpdatePlane(LegoNamedPlane&) +PlaceActor(LegoNamedPlane&) + +#### ParseAction(char*) +Parses a string like ""ATTACH_CAMERA: location direction up", "SPEED speed", "SOUND sound" , "MUTE" and "VISIBILITY". Saves it into the corresponding member. + +### LegoPathController : MxCore +Has PathBoundary (LegoPathBoundary*) + +#### PlaceActor(LegoPathActor*) +Removes actor from current controller, and set it to this. + +#### PlaceActor(LegoPathActor*, LegoAnimPresenter*, ...) +Removes actor from current controller, does through all boundaries, goes through all presenters of them + +### LegoEdge +Has FaceA (LegoWEEdge*), FaceB (LegoWEEdge*), PointA (Vector3), PointB (Vector3). Also utility functions like CWVertex (LegoWEEdge&), CCWVertex (LegoWEEdge&), GetClockwiseEdge(LegoWEEdge&) and GetCounterclockwiseEdge(LegoWEEdge&). + +### LegoUnknown100db7f4 : LegoEdge +Adds Flags, a Mx3DPointFloat and a float and some utility functions like DistanceToMidpoint. + +### LegoWEEdge +Has Edges (LegoUnknown100db7f4*) + +### LegoWEGEdge : LegoWEEdge +Adds EdgeNormal, Flags and other lots of other stuff. + +### LegoPathBoundary : LegoWEGEdge +Has actors and presenters. + +### LegoNamedPlane +Has Name (char*), Position, Direction and Up. Can be serialized. + +### LegoPathActor : LegoActor + +### Mx3DPointFloat : Vector3 +Just a Vector3, doesn't add much. + +## Global Functions + +### KeyValueStringParse(char* p_output, const char* p_command, const char* p_string) +The function KeyValueStringParse searches a text (p_string) for a keyword (p_command). +If it finds the keyword, it copies the value immediately after that keyword into p_output. +It returns TRUE if it found the keyword, otherwise FALSE. + +Example: +p_string = "foo:123, bar:456, baz:789" +p_command = "bar" + +Result: +p_output = "456" +Return value: TRUE