Editing game data

How source files become a football world

The game's text files describe the starting football world. A league file names its country, competitions and clubs. Club files describe teams, kits, staff and rosters. Optional player fields supply identity, ability, skills and personality. The game combines this information when you create a new career or Quick Game.

For everyday changes, begin with Team Editor. It can preserve the surrounding file format while you edit fields, move players and preview kits. This chapter is for understanding the same data, preparing text imports and writing a world by hand.

Work in a personal copy under Documents/My Games/Championship Soccer/DataSets/My World/Data. In this chapter, world Data means that directory. shared Data means Documents/My Games/Championship Soccer/Data. The distinction matters for name lists and other shared resources.

Changing a file does not alter an existing career. Test through a newly imported game, with Always create fantasy players off if you want to inspect the named roster you wrote. Quick start is a prepared world and does not test these edits.

Plain-text rules and names

1. Keep an untouched backup. Begin with a working file similar to the one you want to create.
2. Use a plain-text editor and retain the .txt extension. A word-processing document is not a data file.
3. For newly written files, UTF-8 supports accented names conveniently. Existing historical Windows encodings remain readable. Preserve a working file's encoding when editing it, or deliberately convert a copy to UTF-8.
4. Use one instruction, roster entry or value per line. Keep quoted names and paths as shown in the examples.
5. Put comments on their own lines, starting in the first column with ; or #. Avoid adding explanations after values or indenting comment lines inside player details.
6. Keep referenced names consistent. Example United in a league needs the corresponding Team/Example United.txt.

Accents and Unicode names are supported, including names that differ only in the way an accented character is encoded. Avoid two files that become indistinguishable when case or accent composition is normalised. Use ordinary filenames without path separators or Windows-reserved punctuation.

Blank optional fields may be omitted. Missing information does not mean zero. Keep all club instructions and roster lines before the first $ player block.

A small first world

Create World Data/League/Exampleland.txt:

! Country "Exampleland"
! Names "Data/Names/Exampleland_1st.txt" "Data/Names/Exampleland_2nd.txt"

: Exampleland Premier Division
+ Division 1
+ promotions 0
+ relegations 0
+ reputation 10
Example United
Riverside City
Northport Athletic
Southvale Town

Create a matching club file for each of the four club names. For example, World Data/Team/Example United.txt:

! Name "Example United"
! Reputation 10
! 1 shirt Red1
! 1 shorts White
! 2 shirt White
! 2 shorts Red1

Save first names in Shared Data/Names/Exampleland_1st.txt, one per line:

Alex
Jamie
Morgan
Sam
Taylor

Save surnames in Shared Data/Names/Exampleland_2nd.txt:

Brown
Green
Hill
River
Stone

The short club file intentionally leaves player generation to the game. For a long career, use much larger name lists so that names remain varied. Add a StartYear.txt containing your intended year, then test the world through normal new-career creation.

This example establishes a small league. Add cups and international structures only after the league and club sources work. The game may report other requirements of the selected football world during import. Review those before continuing.

Country and league instructions

Start another division with a new : line. Make promotion and relegation counts agree across connected tiers. Give parallel divisions unambiguous names and appropriate reputations. Country-based qualification considers the relative standing of competing divisions, whereas a rule naming a specific division uses that division.

Put #@cs league-rounds inside its division block. It is intentionally written as a special comment so classic readers can ignore it. In Championship Soccer 2026 it changes the number of meetings. An invalid value is reported and falls back to two for that imported career.

! intro, ! goal and ! metar can assign entrance music, a goal anthem and a weather station to a competition. Place them in the intended competition's block. Copy the placement from a working file when editing a complex international source.

Country and division names also appear in nationality and cup references. Renaming only the displayed heading can leave references behind. Team Editor can maintain many linked names for you.

Cup and tournament file reference

A cup begins with *. Each round has its own participant range and schedule. Put entrant and scheduling rules after the round they belong to. For example, this shows the structure of a four-team knockout cup:

* Exampleland Cup
+ Country "Exampleland"
+ reputation 10
+ round 1 "Semi Final" 1-4 12
+ draw 2
+ add 4 from "Exampleland Premier Division"
+ round 2 "Final" 1-2 24

The example weeks illustrate the format. Check them against your actual league and international calendar before using them in a complete world.

The range 1-32 means places 1 through 32, not a number of goals or a range of acceptable team counts. Ranges beginning above 1 are used in staged competitions where some places enter later. Copy a known working bracket when introducing byes or qualifying rounds.

Entrant instructions

Entry order matters. Do not list an entire field before the first round and assume every later round receives it. If a required cup winner is not yet known, the career can wait for that result, but a sound authoring choice is to draw after the supplying competition finishes. The Entrants dialog in Team Editor makes these rules easier to inspect.

Changing round sizes, groups, promotion paths or weeks can affect the whole season. Test cup draws, progression, hosts and the following season, rather than checking only whether a cup title appears in a menu.

Team files, kits and optional club fields

For every listed club, create Team/Club Name.txt. Keep its ! Name, filename and league entry consistent. National sides use the same kind of team file, named for the country.

A structured ! Staff Manager entry has priority over a conflicting simple manager name. A named manager also takes priority over a contradictory vacancy. Keep one coherent description rather than relying on that conflict handling.

Kits 1, 2 and 3 each support shirt, stripes, sleeves, shorts and socks:

! 1 shirt Red1
! 1 stripes White
! 1 sleeves Red1
! 1 shorts White
! 1 socks Red1

Use colour names from the supplied colour list or the editor's colour picker. An appearance distribution describes a generated population, not four additional kits. Its values are relative weights. The optional personal graphics colour table is explained in Custom football worlds.

Music files themselves are shared and are not stored in the team file or copied by the editor. Entrance music and goal anthems explains locations, supported formats and priority.

Write the squad before player details

After the team instructions, list players before any $ blocks:

Taylor, Alex (1997): GK
Brown, Jamie (1998): D L
Stone, Morgan (1995): D C
River, Sam (2000): M C
Green, Taylor (1999): AM R
Hill, Alex (1996): F C

The recommended pattern is Surname, First name (birth year): Position Side. A name without a comma is retained as one name component. The year qualifier helps distinguish people with the same name and can supply a birth year when no valid detail value does.

Use clear examples such as D C, M L or F R. If the side is absent, creation can select one. With no useful position, squad creation can choose a needed role. A player's suitability for several areas is developed from the complete profile, not from placing his name first in the file.

The game can fill an incomplete squad, so a minimal team file need not contain a complete named roster. For a carefully authored squad, supply enough goalkeepers, defenders, midfielders and forwards. Always create fantasy players must be off to use your named players.

Two ways to supply player details

Inside the team file

After all roster lines, start a block with $ and the matching roster identity:

$ Taylor, Alex (1997)
nationality = England
ability = 135
potential = 160
position = GK
dateOfBirth = 1997-06-23
handling = ++
reflexes = +++
teamwork = +
loyalty = 16

The next $ starts another footballer. Keep the spelling, comma and birth-year suffix consistent with the roster. Do not put new roster lines underneath a detail block.

In a separate file

Create Player/Taylor, Alex (1997).txt and put the assignments directly inside it, without a $ heading:

nationality = England
ability = 135
potential = 160
dateOfBirth = 1997-06-23
handling = ++
reflexes = +++

Player field names recognise familiar variants in spacing and capitalisation. The examples use readable camelCase names. Missing optional details are completed during player creation. One invalid optional value is reported and does not discard every other valid detail.

Identity, birth dates and appearance

A full date uses four year digits and two digits each for month and day. If a valid dateOfBirth conflicts with yearOfBirth, the full date wins. The supported player age at the simulation start is 12–80. An impossible date or unsupported age is reported, and a valid roster birth year may still be used.

The same normalised name and exact birth date identify one footballer across clubs. Different exact dates can distinguish two people with the same name. Without full birth evidence, cross-club matching is deliberately more cautious. Do not use slightly different spelling to manufacture duplicate copies of the same player.

Ability, reputation and potential are different scales from the individual 1–20 skills. Positive potential is used with natural variation during creation, and eventual development still depends on the career. Blank or zero optional reputation/potential values leave normal generation to provide the working values.

All 22 skill and character fields

Every field below is optional. The first thirteen describe physical and technical qualities. Aggression and the remaining fields describe playing tendencies and career character. The ratings glossary explains their football meaning.

Exact values, hints and ranges

An exact skill is a whole number from 1 to 20. A range supplies variation, for example speed = 15-18. Its lower value must come first and both ends must be within 1–20.

0 is the neutral hint, not a skill of zero. The older names keeping for handling, attack-mindedness for offensiveness, adaptation for adaptability, and greediness or moneygreed for greed remain accepted.

Why the created player can differ from the file

Ability is a position-weighted overall target. The game completes the physical and technical profile, then balances those first thirteen skills to that target while keeping their relative strengths as closely as the allowed range permits. Goalkeepers and outfield roles weight the same qualities differently.

For example, ability 80 combined with every physical skill set to 20 asks for conflicting things. Creation lowers the profile to the intended overall level. An exact input skill can therefore change. Aggression and the later character values are handled separately from that physical-skill balancing.

Hints and ranges intentionally vary between new games. Exact values reduce that variation, but do not disable ability balancing. Potential also has creation variation. If repeatability matters, compare several newly created careers and assess the intended strengths, age, role and level rather than expecting every displayed digit to equal its source text.

Country identity and national-team eligibility

Use a recognised country name in nationality. When no nationality is supplied, the club's country normally provides it. A footballer can play abroad without becoming eligible for that club's national team.

The selected world may know a country as an active football nation through ! Country or ! AdditionalCountry. A nationality can also be retained as a reference country when its shared first-name and surname lists exist. A reference nationality alone does not add playable leagues, national-team fixtures or a tournament.

Shared Data/Nationalities.txt can recognise alternative names:

[exampleland]
display = Exampleland
names = Exampleland
alias = Exampleland
alias = Republic of Exampleland
rewrite = Republic of Exampleland

Aliases are deliberate equivalences, not guesses about geography. A rewrite does not rename club files, players or internal competition references. Personal definitions can refine the supplied catalogue while retaining supplied aliases. The Shared data editor offers these same fields.

Structured staff data

Staff use a team-header instruction before the roster and player blocks:

! Staff Manager "Alex Brown" [id="example:manager:1"; nation="England"; born=1978-04-12; profile=Generalist; level=70; potential=78; reputation=68; worldKnowledge=55; rootNation="England"; preferredFormation="4-4-2"]

The semicolons in this example are required separators inside the staff record. Quote names and text containing spaces. Keep a person's identity stable when several source assignments refer to that same person.

The detailed role picker also covers performance and rehabilitation coaches, video and match analysts, individual coaches, sports scientists, youth coordinators, academy staff, chief and specialist scouts, loan-player staff and medical staff. A specialised title can map to a broader career job. Use the picker rather than inventing an unrecognised functional role.

Source contract notes are not the same as negotiating an active career contract. Check the resulting staff in a test career. Formation preferences influence computer-controlled clubs together with the manager's tactical knowledge and available players, rather than forcing a fixed eleven.

Scouting-provider source files

ScoutingProvider/*.txt describes services offered to clubs. A complete file has a provider header followed by product and market blocks. Copy a supplied provider as a starting point, or use the editor's forms.

! Provider "myprovider" 1
! Name "My Provider"

: Product "myprovider.local" 1
+ Name "Local Player Reports"

: Market "myprovider.home" 1
+ Name "Home Market"

This is the block structure, not a complete sellable service. Retain and adapt the required fields from a working catalogue. Product and market identifiers must refer to real entries in the same provider.

Percentage-like values in the text use hundredths of a percent: 10000 means 100%, 2500 means 25% and 1800 means 18%. The graphical editor converts these into familiar percentages, so do not copy the editor's percentage directly into a raw source field without converting it.

Coverage has separate top-division and lower-division values. Contribution has three values, for discovery, skills and potential. Age, Divisions and Club reputation contain lower and upper bounds. Products can supply identity, sporting, development and market-contract information, with monthly or seasonal billing. Use the editor's multiple-choice fields for combinations.

A custom world's own ScoutingProvider folder supplies its provider catalogue. If the folder is absent, the installed catalogue is used. Test that the intended products are actually offered to a suitable club, including their area, age and reputation conditions.

Starting year and age checks

Save one year in World Data/StartYear.txt:

2026

Supported years are 1000–9999. Before creation, the game uses a previously chosen successful year if one exists, otherwise the selected world's suggestion, then the installed suggestion and finally the current default of 2025. The displayed value can be changed and is authoritative for that new world.

Check a few known birth years after import. A player born in 2001 is treated against the simulation's starting year, not your computer's current date. Changing StartYear.txt later does not recalculate an existing save. If creating a historical world, use contemporary birth years and squads appropriate to the chosen season.

Script and CSV authoring reference

The optional Scripts screen runs Lua against the opened editor database. Run produces a preview, Apply accepts it, and the database still needs Save. See the editor workflow before running your first script.

Collections support iteration with ipairs, counting with #, indexed access and :find(name). Find requires an unambiguous name, ID or key. A club has club.players and club.staff, a league has league.clubs and league.players, and a cup has cup.rounds.

local club = assert(data.clubs:find("Example United"))
local player = club.players:add {
    name = "Brown, Alex",
    age = 17,
    nationality = "Exampleland",
    position = "M C"
}
player.ability = 100
player.skills.speed = "++"
print(player.name)

Properties use normalised field names, such as dateOfBirth, yearOfBirth, firstName and lastName. Unset values are nil. Skill hints remain strings. player.age means database start year minus birth year. Setting age changes the birth year while preserving an existing month and day where possible.

:fields() lists fields. :get(key) and :set(key, value) handle source fields directly. :values(key) and :setValues(key, values) handle repeated values. :moveTo(destination) moves a player or club, and :remove() deletes an entry. After adding or removing entries, query the collection again to get its current members.

Some roster entries share a separate profile. For relative edits such as increasing age, first collect the intended target values and then write them, as the built-in age example does. Otherwise a shared source value could be incremented twice.

Import a four-column CSV

The built-in CSV example expects name;birth date;nationality;position, with no header. Select the file as Input file:

Brown, Alex;2009-07-15;Exampleland;M C
Green, Sam;2007-02-02;Exampleland;D L

local club = assert(data.clubs:find("Example United"))
local rows = csv.parse(input.readText(), ";")
for line, row in ipairs(rows) do
    assert(#row == 4, "CSV: " .. line)
    club.players:add {
        name = text.trim(row[1]),
        dateOfBirth = dates.parse(row[2], "yyyy-mm-dd"),
        nationality = text.trim(row[3]),
        position = text.trim(row[4])
    }
end
print(#rows)

Set the database start year appropriately for these sample ages. Running this example again adds entries again, so inspect the preview and existing squad before applying. This is a creation example, not a duplicate-aware update routine.

Scripts do not write arbitrary external files. The editor's own save and export actions publish the edited data. A failed run or cancellation discards the trial, and a successful applied preview is one database Undo action.

Check and test the finished world

1. Check every league-to-team reference and every roster-to-profile name.
2. Open the world in Team Editor and run Check. Review missing names, club files, ambiguous profiles and duplicate people.
3. Save, create a new normal career from this exact source, and disable fantasy players when checking named squads.
4. Inspect the league table, squads, kits, nationality, birth years, positions, staff and overall strengths.
5. Review every import warning and save the test career under a new name.
6. Advance the calendar through the relevant league, cup and international periods. For structural changes, test the season transition too.
7. Test the final ZIP separately from your development folder.

If a player did not change, check the selected copy, separate Player-file priority and whether you opened an old save. If names look wrong, inspect the text encoding. If the career uses an unexpected year, inspect the year shown before import. If a named player disappears, check exact identity and birth-date duplicates.

The current import report describes repairs used in that career. Keep it with your test notes, then correct the actual source rather than assuming the file was rewritten. Import warnings and Troubleshooting explain the next steps.