### Network Demos

This document describes how network demos are implemented.

#### Fundamental Structure

A network demo only needs to contain four things:

  - Header
  - Input commands
  - Network messages
  - Console commands

Each of these will have a unique identifier, and the size of the data
immediately follows.  So something like (overly simplified):

    void CS_SaveCommandToDemo(cs_cmd_t *cmd)
    {
        *cs_demo_p++ = CS_DEMO_INPUT_COMMAND_MARKER;
        *cs_demo_p++ = sizeof(cs_cmd_t);
        memcpy(cs_demo_p++, cmd, sizeof(cs_cmd_t));
    }

#### Archive:

Fundamentally, a demo is all network messages and local player input received
during a single map as well as a header (described above).  However, demos can
only be distributed as members of a "demo archive", which is a ZIP file with a
very specific structure.  The expected structure is:

  - `20110102_175201-0500.ecd`
    - info.json
    - 0
      - info.json
      - toc.json
      - log.txt
      - demodata.bin
      - save1.sav
      - save1.png
      - save2.sav
      - save2.png
      - saveN.sav
      - saveN.png
    - 1
      - ...
      - demodata.bin
      - ...

The timestamp in the filename is to ensure that demo files are not haphazardly
overwritten, but it is not a requirement.  The archive splits up the demo so
that there's 1 demo for each map, and these demos are stored in sequentially
numbered folders.  The save games are used as checkpoints for quick rewinding
and fast-forwarding, and the screenshots and log will be useful in various ways
to users.

#### Top-Level info.json Contents:

  - Version
  - Name
  - Author
  - Date Recorded

#### Per-map info.json Contents:

  - Resources
    - name
    - type (IWAD/PWAD/DEH/BEX/EDF)
    - SHA-1 hash
  - Settings (basically JSON settings dump)
  - Length of Demo (in seconds)

This format will be easy to extend, so any field can be added.

##### toc.json

`toc.json` maps savegames to indices.  The main purpose of this is so that a
viewer knows at what point in the demo the savegame refers to, but the reason
for keeping the information separate is so that checkpoints can be added or
deleted by a viewer.

##### log.txt

`log.txt` contains the events that occurred during the game, such as
`[UD]Ladna was splattered by [UD]Ralphis' super shotgun.`.  When stat are
added (likely in JSON format), they will be separate from this game log file.

#### demodata.bin:

`demodata.bin` is the main demo file, and contains different things based on
whether the demo is a serverside or clientside demo.

  - Header
    - clientside or serverside (1 or 2 respectively)
    - WADs (ordered, names and SHA-1 hashes)
    - Settings (`cs_current_settings` dump)
    - Map name
    - Date/Time
    - Length (indices)
  - Index.
    - Network Message
    - Local Player Input Command
    - Local Player Console Command

#### Robustness

Clients should handle the absence of files other than `demodata.bin` as
gracefully as possible; the only truly indispensible file is the demo itself -
in fact, all the information can be re-created from the demo.

#### Base Technologies (Archival/Compression)

As noted above, demos are ZIP files, readable by any compliant ZIP utility.
This is intended to make demos more robust and more usable.  Users are free,
for instance, to add whatever fields to the JSON info files.  ZIP is also a
common format, readable in practically all popular programming languages.

vim:tw=79 sw=4 ts=4 syntax=mkd et: