Creating timeline tracks - xivintheshell/xivintheshell GitHub Wiki

Though XIV in the Shell supports track creation within the browser, the process of manually adding individual markers can become quite tedious for longer fights. We recommend using our csv2track Python script (or the colab notebook for non-technical users) to convert an annotated FFLogs cast event CSV to the shell marker format.

Getting a log

To export a log of boss "cast" events (which acounts for most casts and telegraphs), select "enemies" below the encounter name, switch the log to the "events" view, and select the "casts" tab. image

Make sure "include all begin casts" (above the table of events) is selected. Scroll to the bottom of the page, and click the "CSV" button to the bottom right of the events table. Import the resulting file in the spreadsheet editing software of your choice.

Annotating the log

See this folder for examples of previous official tracks created in Google Sheets.

Add the following 4 columns to the log export:

  • Track: the number of the track (-1 for the untargetable track, 0 for the bottom track, and increasing integers for higher tracks)
  • Color: the case-sensitive string of the color the use (see the manual marker adding tab in XIV in the Shell for available colors)
  • Override Description: text to display on the marker (otherwise will be the name in the Ability column)
  • Hide Text: if "y", then hides text and only displays it on mouseover

Only rows that have populated Track and Color fields will be processed by the csv2track script.

You will most likely need to add more rows to account for visual telegraphs or mechanic resolutions that are not included in the cast events. Consider highlighting these rows to ensure its clear which events were sourced from a log and which were manually added.

When choosing what to include in the spreadsheet, consider these factors:

  • Does the boss have a visible cast bar for the move? Even if the cast itself doesn't do anything, players may use this as an in-game reference for parts of their rotation.
  • Does the ability have multiple variations (e.g. stack first, then spread; vs. spread first, then stack)? Make sure the displayed cast names account for this, and use the "Override Description" column as needed.
  • Are there telegraphs or critical timing windows that are visible in-game, but not by any cast or log events? For example, if a boss does an extremely long teleport across the room, it may not be visible in a log, but is still important for players to know when to use gap-closers or move.
  • Is the mechanic a long sequence of repeated hits/dodges, like an Akh Morn multi-hit stack or an Exaflare dodge? Consider making the text label only for the first hit, and showing the remaining hits as hidden-text dots.

Coloring convention

I (shanzhe) roughly adhere to a coloring convention inspired by graphics like this to represent different types of mechanics. However, there are many more mechanic types than primary colors, so don't hesitate to diverge from these rules for any reason, whether aesthetic or practical.

  • Red: tankbusters, stuns, down for the count, or extreme danger mechanics
  • Orange: telegraphed mechanic or dodge needed
  • Yellow: cast bar storing information for later
  • Green: unused
  • Cyan: debuff appearance or resolution, or an instance of a mechanic appearance/resolution
  • Blue: raidwide or other unavoidable damage
  • Purple: tower soaks, mechanics with long casts/resolutions, or enrage
  • Pink: mechanic-provided buffs or LB generation
  • Grey: targetability changes, adds spawn, or general information (technically unavailable in the web UI for anything other than untargetability)

Useful filter expressions

The following FFLogs filter expressions are extremely useful for analyzing logs, and reveal events that are not necessarily included in boss casts.

  • type="targetabilityupdate": All targetable/untargetable transition events. Some boss/add deaths are included here, but not all; check the enemy "deaths" tab of the log to be sure.
  • type="headmarker": Represents when a head marker (stack, spread, defamation, etc.) becomes visible. Useful for telegraphs that don't immediately follow a cast bar.

Also check other log tabs (especially Debuffs, Damage Taken, and Resources) to find timings that aren't included in the cast list.