docs: add line 41 documentation (quisquous#4199)

Author: quisquous

docs/LogGuide.md

@@ -1860,7 +1860,12 @@ ACT Log Line Examples:
 
 ### Line 41 (0x29): SystemLogMessage
 
-This log line is sent when there are system log messages:
+This log line is sent when there are system log messages.
+As game chat log lines are read from memory in the FFXIV ACT plugin,
+[Line 41](#line41) can be sent both before or after the corresponding [Line 00](#line00).
+That said, they are usually sequential in the network log,
+and so there is no timing advantage to using one over the other,
+but the system log message will have a correct timestamp.
 
 ```log
 [10:38:40.066] SystemLogMessage 29:00:901:619A9200:00:3C
@@ -1873,30 +1878,26 @@ This log line is sent when there are system log messages:
 [10:55:06.707] SystemLogMessage 29:8004001E:B3A:00:00:E0000000
 ```
 
-TODO: write a better explanation here and understand these parameters.
-It'd be nice to figure out what these mean so we could replace
-zone closing and npc dialog with these lines.
-
 <!-- AUTO-GENERATED-CONTENT:START (logLines:type=SystemLogMessage&lang=en-US) -->
 
 #### Structure
 
 ```log
 Network Log Line Structure:
-41|[timestamp]|[?]|[id]|[param0]|[param1]|[param2]
+41|[timestamp]|[instance]|[id]|[param0]|[param1]|[param2]
 
 ACT Log Line Structure:
-[timestamp] SystemLogMessage 29:[?]:[id]:[param0]:[param1]:[param2]
+[timestamp] SystemLogMessage 29:[instance]:[id]:[param0]:[param1]:[param2]
 ```
 
 #### Regexes
 
 ```log
 Network Log Line Regex:
-^(?<type>(?:41))\|(?<timestamp>(?:[^|]*))\|(?:[^|]*\|)(?<id>(?:[^|]*))\|(?<param0>(?:[^|]*))\|(?<param1>(?:[^|]*))\|(?<param2>(?:[^|]*))\|
+^(?<type>(?:41))\|(?<timestamp>(?:[^|]*))\|(?<instance>(?:[^|]*))\|(?<id>(?:[^|]*))\|(?<param0>(?:[^|]*))\|(?<param1>(?:[^|]*))\|(?<param2>(?:[^|]*))\|
 
 ACT Log Line Regex:
-(?<timestamp>^.{14}) SystemLogMessage (?<type>29):[^:]*:(?<id>(?:[^:]*)):(?<param0>(?:[^:]*)):(?<param1>(?:[^:]*)):(?<param2>(?:[^:]*))(?:$|:)
+(?<timestamp>^.{14}) SystemLogMessage (?<type>29):(?<instance>(?:[^:]*)):(?<id>(?:[^:]*)):(?<param0>(?:[^:]*)):(?<param1>(?:[^:]*)):(?<param2>(?:[^:]*))(?:$|:)
 ```
 
 #### Examples
@@ -1915,6 +1916,67 @@ ACT Log Line Examples:
 
 <!-- AUTO-GENERATED-CONTENT:END -->
 
+The `instance` parameter is identical to `instance` in [actor control line)](#line33).
+The first two bytes are the update type
+and the second two bytes are ids in the [InstanceContent table](https://github.com/xivapi/ffxiv-datamining/blob/master/csv/InstanceContent.csv).
+
+The `id` parameter is an id into the [LogMessage table](https://github.com/xivapi/ffxiv-datamining/blob/master/csv/LogMessage.csv).
+
+id (hex) | Link | Shortened Message
+--- | --- | ---
+0x2EE | [link](https://xivapi.com/LogMessage/750?pretty=true) | You obtain (an item)
+0x7DC | [link](https://xivapi.com/LogMessage/2012?pretty=true) | will be sealed off in X seconds
+0x7DD | [link](https://xivapi.com/LogMessage/2013?pretty=true) | is sealed off
+0x7DE | [link](https://xivapi.com/LogMessage/2014?pretty=true) | is no longer sealed
+
+The log message itself determines the other parameters.
+It seems that `IntegerParameter(1)` in the log message corresponds to `param1`
+and `IntegerParameter(2)` corresponds to `param2`.
+It is not clear what `param0` does or how other `Parameter` functions work.
+
+Here are two network log lines:
+
+```log
+41|2022-01-11T16:28:50.6340000-08:00|80030054|7DC|02|1008|0F|1a1b91bd4bf5d5e1^M
+00|2022-01-11T16:28:50.0000000-08:00|0839||The shell mound will be sealed off in 15 seconds!|3a0befeef04e203b^M
+```
+
+`80030054` is the instance.
+`8003` means instanced content.
+(`8004` means trust content.)
+`0054` is the [InstanceContent](https://xivapi.com/InstanceContent/84?pretty=true) id,
+so this is The Dead Ends.
+
+`7DC` is the `id`, which [corresponds](https://xivapi.com/LogMessage/2012?pretty=true) to:
+`"<Clickable(<SheetEn(PlaceName,2,IntegerParameter(1),2,1)\/>)\/> will be sealed off in <Value>IntegerParameter(2)<\/Value> <If(Equal(IntegerParameter(2),1))>second<Else\/>seconds<\/If>!"`
+
+Use the log message itself to determine what `param1` and `param2` mean, if anything.
+
+In this case,
+`param1` is `1008`, which from the log message you can determine is a PlaceName id.
+Looking this up in the [PlaceName](https://xivapi.com/PlaceName/4104?pretty=true) table gets "Shell Mound".
+
+`param2` is `0x0F`, which from the log message is used for the seconds in the message, i.e. 15 in decimal.
+
+Here's one other example:
+
+```log
+41|2022-02-18T22:03:00.5130000-08:00|1B01EA|2EE|C2BD6401|758A|45D530|9efb90e26e3b41c3
+00|2022-02-18T22:03:00.0000000-08:00|0BBE||You obtain a little leafman.|51d9427a6354d3af
+```
+
+`2EE` is the `id`, which [corresponds](https://xivapi.com/LogMessage/750?pretty=true) to:
+`"<Clickable(<If(Equal(ObjectParameter(1),ObjectParameter(2)))>you<Else/><If(PlayerParameter(7))><SheetEn(ObjStr,2,PlayerParameter(7),1,1)/><Else/>ObjectParameter(2)</If></If>)/> <If(Equal(ObjectParameter(1),ObjectParameter(2)))>obtain<Else/>obtains</If> <SheetEn(Item,1,IntegerParameter(1),1,1)/>."`
+
+Here, `param1` is `758A`, which [corresponds](https://xivapi.com/Item/30090?pretty=true) to "Little Leafman" in the `Item` table.
+It is unclear how `ObjectParameter` and `PlayerParameter` work here.
+
+Future work:
+
+- What is `param0`? Is it just skipped?
+- How do `PlayerParameter` and `ObjectParameter` work in the `LogMessage` table?
+- Some log messages don't show as 41 lines, e.g. "You have arrived at a vista" or "Engage!".
+
 <a name="line251"></a>
 
 ### Line 251 (0xFB): Debug

resources/netlog_defs.ts

@@ -728,7 +728,7 @@ const logDefinitions = {
     fields: {
       type: 0,
       timestamp: 1,
-      // unknown: 2,
+      instance: 2,
       id: 3,
       param0: 4,
       param1: 5,

test/unittests/netregex_test.ts

@@ -379,11 +379,12 @@ describe('netregex tests', () => {
     ] as const;
     regexCaptureTest((params?: RegexUtilParams) => NetRegexes.systemLogMessage(params), lines);
 
-    const matches = lines[0].match(NetRegexes.systemLogMessage())?.groups;
+    const matches = lines[1].match(NetRegexes.systemLogMessage())?.groups;
     assert.equal(matches?.type, '41');
-    assert.equal(matches?.id, '901');
-    assert.equal(matches?.param0, '619A9200');
-    assert.equal(matches?.param1, '00');
-    assert.equal(matches?.param2, '3C');
+    assert.equal(matches?.instance, '8004001E');
+    assert.equal(matches?.id, '7DD');
+    assert.equal(matches?.param0, 'FF5FDA02');
+    assert.equal(matches?.param1, 'E1B');
+    assert.equal(matches?.param2, '00');
   });
 });

test/unittests/regex_test.ts

@@ -390,10 +390,11 @@ describe('regex tests', () => {
     ] as const;
     regexCaptureTest((params?: RegexUtilParams) => Regexes.systemLogMessage(params), lines);
 
-    const matches = lines[0].match(Regexes.systemLogMessage())?.groups;
-    assert.equal(matches?.id, '901');
-    assert.equal(matches?.param0, '619A9200');
-    assert.equal(matches?.param1, '00');
-    assert.equal(matches?.param2, '3C');
+    const matches = lines[1].match(Regexes.systemLogMessage())?.groups;
+    assert.equal(matches?.instance, '8004001E');
+    assert.equal(matches?.id, '7DD');
+    assert.equal(matches?.param0, 'FF5FDA02');
+    assert.equal(matches?.param1, 'E1B');
+    assert.equal(matches?.param2, '00');
   });
 });

ui/raidboss/emulator/data/network_log_converter/LineEvent0x29.ts

@@ -7,6 +7,7 @@ const fields = logDefinitions.SystemLogMessage.fields;
 
 // SystemLogMessage event
 export class LineEvent0x29 extends LineEvent {
+  public readonly instance: string;
   public readonly id: string;
   public readonly param0: string;
   public readonly param1: string;
@@ -15,6 +16,7 @@ export class LineEvent0x29 extends LineEvent {
   constructor(repo: LogRepository, line: string, parts: string[]) {
     super(repo, line, parts);
 
+    this.instance = parts[fields.instance] ?? '';
     this.id = parts[fields.id] ?? '';
     this.param0 = parts[fields.param0] ?? '';
     this.param1 = parts[fields.param1] ?? '';