Package puffer

Overview ▾

Package puffer ▷

Data Protocol Auto-Generator

Puffer module allows you to define data protocols for the client and the server. It auto-generates code for both the client and the server.

Supported Data Types

The table below shows the supported data type and their dictations with corresponding data types.

Puffer also recognizes user defined protocol data as a valid data type as well.

┌──────────────────────────┬───────────────────────────────────┐
│                          │      Corresponding Data Type      │
├──────────────────────────┼───────────┬──────────┬────────────┤
│ JSON Data Type Dictation │     Go    │    C#    │     C++    │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                       u8 │     uint8 │     byte │    uint8_t │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                      u16 │    uint16 │   ushort │   uint16_t │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                      u32 │    uint32 │     uint │   uint32_t │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                      u64 │    uint64 │    ulong │   uint64_t │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                       i8 │      int8 │    sbyte │     int8_t │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                      i16 │     int16 │    short │    int16_t │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                      i32 │     int32 │      int │    int32_t │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                      i64 │     int64 │     long │    int64_t │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                      f32 │   float32 │    float │  float32_t │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                      f64 │   float64 │   double │  float64_t │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                     bool │   boolean │     bool │       bool │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                   string │    string │   string │     string │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                      b[] │    []byte │   byte[] │       byte │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                     u8[] │   []uint8 │   byte[] │   uint8_t* │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                    u16[] │  []uint16 │ ushort[] │  uint16_t* │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                    u32[] │  []uint32 │   uint[] │  uint32_t* │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                    u64[] │  []uint64 │  ulong[] │  uint64_t* │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                     i8[] │    []int8 │  sbyte[] │    int8_t* │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                    i16[] │   []int16 │  short[] │   int16_t* │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                    i32[] │   []int32 │    int[] │   int32_t* │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                    i64[] │   []int64 │   long[] │   int64_t* │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                    f32[] │ []float32 │  float[] │ float32_t* │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                    f64[] │ []float64 │ double[] │ float64_t* │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                   bool[] │ []boolean │   bool[] │      bool* │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                 string[] │  []string │ string[] │      char* │
├──────────────────────────┼───────────┼──────────┼────────────┤
│                    b[][] │  [][]byte │ byte[][] │      byte* │
└──────────────────────────┴───────────┴──────────┴────────────┘

JSON Definitions

Puffer module uses JSON format to define protocol data.

[IMPORTANT] Duplicate Protocol Name: You must NOT have duplicate protocol names per package name in your JSON definitions. JSON does allow duplicate keys, but puffer does not work properly with duplicate keys.

The format:

{
  "$(Protocol Name)": {
    "package": "$(Package Name for auto-generated Go code)"", // package is required. this will also become the directory
    "ver": // Not used, but required.
    "cmd": // Not used, but required.
    "properties": {
      "$(Property Name)": {
        "propertyType": "$(Data Type Dictation)",
        "comment":      "$(Optional comment)"
      },
    }
  }
}

▶︎ Example:

{
  "Movement": {
    "package": "movement",
    "ver": 0,
    "cmd": 0,
    "properties": {
      "characterID": { "type": "string", "comment": "Character texture ID." },
      "x":           { "type": "f32", "comment": "X position of the character on the map." },
      "y":           { "type": "f32", "comment": "Y position of the character on the map." },
      "z":           { "type": "f32", "comment": "Z position of the character on the map." },
      "velocity":    { "type": "f32", "comment": "Character movement speed" },
      "msg":         { "type": "b[]", "comment": "Optional extra data to share" }
    }
  }
}

▶︎ Example With Protocol As Data Type:

{
  "TransportData": {
    "ver": 0,
    "cmd": 0,
    "package": "movement",
    "properties": {
      "movement":  "Movement",   // This is defined as a protocol data and uses as a data type
      "movements": "Movement[]"  // You may use the protocol data as an array as well.
      "messages":  "b[][]",
      "sequence":  "u16"
    }
  },
  "Movement": {
    "package": "movement",
    "ver": 0,
    "cmd": 0,
    "properties": {
      "characterID": "string",
      "x":           "f32",
      "y":           "f32",
      "z":           "f32",
      "velocity":    "f32",
      "msg":         "b[]"
    }
  }
}

The property type can include the package name using the word "." if it is a custom data type. If it does not include the package name, its package name is the same as the protocol package name.

e.g. "movement.Movement" -> package name: "movement", property type: "Movement"
e.g. "Movement" protocol package Name: "car" -> package name: "car", property type: "Movement"

Params

Puffer module needs Params to configure the auto-code-generator.

Params.DefinitionPath - The relative path of the definition JSON files.
                        The path must be a relative path from the auto-generator is executed from.
                        The path must be a directory. The code generator will look for all JSON files in the given directory recursively.

Params.OutputPath     - The relative output path of for the auto-generated code files to be placed.
                        The path must be a relative path from the auto-generator is executed from.
                        The path must be a directory.
                        The output directory structure example:

                        $(output_path_directory) ─┐
                                                  ├─ go/ ───── $(package_name)/ ─┬── $(protocol_name_1 in lowercase).go
                                                  │                              ├── $(protocol_name_2 in lowercase).go
                                                  │                              └── $(protocol_name_3 in lowercase).go
                                                  │
                                                  ├─ cs/ ───── $(package_name)/ ─┬── $(protocol_name_1 in PascalCase).cs
                                                  │                              ├── $(protocol_name_2 in PascalCase).cs
                                                  │                              └── $(protocol_name_3 in PascalCase).cs
                                                  │
                            (Not implemented yet) └─ cpp/ ──── $(package_name)/ ─┬── $(protocol_name_1 in PascalCase).cpp
                                                                                 ├── $(protocol_name_2 in PascalCase).cpp
                                                                                 └── $(protocol_name_3 in PascalCase).cpp

Params.ModulePath     - Go module package path for the auto-generated code files.
                        Import will use this path.

Index ▾