OpenFUT-Core/MODDING.md

OpenFUT Modding Guide

All game content is driven by JSON files in the data/ directory. You can add new cards, packs, objectives, and SBCs without touching any Rust code.

The server reloads data files on startup. After changing a file, restart openfut-core to pick up the changes.

---

Cards — data/cards/*.json

Each file contains a JSON array of CardDefinition objects. All files in the directory are loaded at startup.

[
  {
    "id":        "card_unique_id",
    "name":      "Player Name",
    "overall":   82,
    "position":  "ST",
    "nation":    "Brazil",
    "league":    "Brasileirao",
    "club":      "Flamengo",
    "pace":      88,
    "shooting":  85,
    "passing":   74,
    "dribbling": 82,
    "defending": 38,
    "physical":  76,
    "rarity":    "gold",
    "image_path": null
  }
]

Valid rarity values: bronze, silver, gold, raregold, totw, hero, icon

Valid positions: GK, CB, LB, RB, CDM, CM, CAM, LM, RM, LW, RW, ST, CF

• id must be unique across all card files.
• overall is 1–99.
• Attribute values are 1–99.
• image_path can be a relative path to an image or null.

---

Packs — data/packs/*.json

Each file contains a JSON array of PackDefinition objects.

[
  {
    "id":          "my_custom_pack",
    "name":        "Custom Pack",
    "description": "12 random gold players.",
    "cost_coins":  7500,
    "slots": [
      {
        "count":          12,
        "min_overall":    75,
        "rarity_filter":  ["gold", "raregold"],
        "guaranteed_rare": false
      }
    ]
  }
]

Each slot defines one group of cards to draw:

• count — how many cards to draw for this slot.
• min_overall — minimum overall rating (inclusive), or null for no filter.
• rarity_filter — array of rarity strings to draw from, or null for any rarity.
• guaranteed_rare — if true, this slot's cards are marked as rare.

A pack can have multiple slots (e.g., one slot of 11 gold cards + one guaranteed rare slot of 1 card).

---

Objectives — data/objectives/*.json

Each file contains a JSON array of ObjectiveDefinition objects.

[
  {
    "id":             "daily_score_3",
    "title":          "Hat-Trick Hero",
    "description":    "Score 3 goals in one session.",
    "objective_type": "daily",
    "metric":         "goalsscored",
    "target":         3,
    "reward_coins":   500,
    "reward_xp":      200,
    "reward_pack_id": null
  }
]

Valid objective_type values: daily, weekly, milestone, lifetime, season

Valid metric values:

Metric	Incremented by
matcheswon	Winning a match
matchesplayed	Playing any match
goalsscored	Goals scored in a match
packsopened	Opening a pack
sbcscompleted	Completing an SBC
coinsearned	Coins awarded after a match

• reward_pack_id must match a pack id from data/packs/ or be null.
• Daily objectives are auto-reset to 0 at midnight UTC.

---

SBCs — data/sbcs/*.json

Each file contains a JSON array of SbcDefinition objects.

[
  {
    "id":          "my_sbc",
    "name":        "Custom SBC",
    "description": "Submit 5 gold players for a reward.",
    "expires_at":  null,
    "requirements": {
      "squad_size":                  5,
      "min_overall":                 75,
      "max_overall":                 null,
      "required_leagues":            ["Premier League"],
      "required_nations":            [],
      "required_clubs":              [],
      "min_players_from_same_league": null,
      "min_players_from_same_nation": null,
      "min_players_from_same_club":   null
    },
    "reward": {
      "coins":   1000,
      "xp":      300,
      "pack_id": null
    }
  }
]

Requirements:

• squad_size — exact number of cards to submit (required).
• min_overall — average overall must meet or exceed this (optional).
• max_overall — no individual card may exceed this (optional).
• required_leagues — at least one card from each listed league.
• required_nations — at least one card from each listed nation.
• required_clubs — at least one card from each listed club.
• min_players_from_same_league — max count of any single league ≥ this.
• min_players_from_same_nation — max count of any single nation ≥ this.
• min_players_from_same_club — max count of any single club ≥ this.

Cards submitted to an SBC are permanently consumed from the club's collection.

---

Tips

• Use unique id values that won't collide with future official cards. A good convention is card_<nation>_<number>, e.g. card_br_042.
• You can have multiple JSON files per directory — they are all merged at load time.
• Invalid JSON will prevent the server from starting; check the log output.
• Cards referenced by packs must exist in data/cards/ or they will not be drawn.