package.xml reference

package.xml sits at the root of a structured pack and marks the folder as a pack. This page is the complete current contract: what the game reads, what only the tools read, and what happens when the file disagrees with the folder it sits in.

Minimal safe manifest

<?xml version="1.0" encoding="utf-8"?>
<Package Id="MyPack" Name="My Pack" Author="You" Version="1.0" />

placed at resources/packages/MyPack/package.xml. The folder name and the Id are the same string; everything else is optional.

Identity: folder and Id

The game identifies a pack by its folder name. The Id attribute is the same identity written down inside the pack, and the two must match:

• The drag-and-drop installer reads Id, refuses a pack without one, and creates the folder from it (resources/packages/<Id>/, or resources/packages/defaults/<Id>/ for Type="Defaults"). A pack installed this way can never disagree with itself.
• A pack copied in by hand is loaded under whatever folder name it has. Characters, traits, items and images load regardless. Anything addressed by pack id, which today means jobs, buildings and heritage, is skipped when the declared Id differs from the folder, and gamelog.txt says so.

The Id grammar is deliberately narrow so it works as a folder name on every platform: letters, digits, _, - and ., at most 64 characters, no leading dot, no trailing dot or space, and none of the Windows reserved device names (con, nul, com1, …). Case is preserved, but two packs whose ids differ only by case collide on Windows and macOS, so treat ids as case-insensitive when choosing one.

Attributes on <Package>

Attribute	Read by	Notes
Id	game, installer, validator, Content Editor	Required. Identity; must equal the folder name (see above).
Type	game, installer, validator	Content (default), Addon, Defaults or Override. Decides how far the pack’s fallback art reaches; see Package roles. Any other value is refused by the installer.
Extends	game, installer, validator	Required when Type="Addon": the Id of the pack this addon extends.
RandomGirlNaming	game, validator	Pack-wide default for random templates: engine (default), template or pool. See Girls.girlsx schema.
NamePool	game, validator	Names file used when RandomGirlNaming="pool", relative to the pack root.
Name	Content Editor	Display name shown when browsing packs in the editor. The game itself lists packs by Id and never reads Name.
Author, Version, Description	Content Editor	Metadata only.
ArtStyle	Content Editor	drawing, rendering, photo or genai: the pack’s predominant art style, shown when browsing packs (1.17.2+). The game ignores it.
RequiresEngine	validator only	Minimum game version, e.g. 1.15.6. The validator uses it to decide which version-gated checks apply. The game does not read it and does not warn players, so state the minimum version in your README as well.

Child elements

Element	Read by	Notes
<Requires><Pack Id="..."/>...</Requires>	game, validator, Content Editor	Packs this one depends on. The game reports a missing dependency in the in-game Content Manager; the Content Editor shows it in the pack details. A message overlay that targets another pack’s job should declare that pack here.
<Tags><Tag>...</Tag></Tags>	nothing today	Free-form labels. Preserved by the editor, used by no surface yet.

Unknown attributes and elements are ignored, so a manifest written for a newer game still loads on an older one; it just loses the newer fields’ effect.

A fuller example

<?xml version="1.0" encoding="utf-8"?>
<Package
    Id="harbour_district"
    Name="Harbour District"
    Author="Your Name"
    Version="1.2"
    Description="Three dockside workers, a tavern job and the gear to go with it."
    ArtStyle="drawing"
    RequiresEngine="1.19.0">
    <Requires>
        <Pack Id="core_extras" />
    </Requires>
    <Tags>
        <Tag>characters</Tag>
        <Tag>jobs</Tag>
    </Tags>
</Package>

What the installer checks

The drag-and-drop installer validates before it copies anything, and refuses the pack with a message on screen when:

Problem	Message
no package.xml at the pack root (or in its single subfolder)	Not a pack
the file is not well-formed XML	package.xml could not be parsed
the root element is not <Package>	root element must be <Package>
Id missing or empty	missing a non-empty Id attribute
Id outside the grammar above	not a valid pack identifier
Type outside the four spellings	not a pack type
Type="Addon" without Extends	no Extends attribute
Type="Defaults" carrying characters, traits, items, jobs or scripts	ship the rest as its own package
Type="Defaults" with no images	would provide nothing
no recognised content at all	expected a Characters/, buildings/ or jobs/ folder, or a .girlsx/.rgirlsx/.traitsx/.itemsx file
a pack with the same Id already installed	remove it first to replace it

The pack validator runs the same identity and role checks from the command line, plus the content checks described on the Tools page.

Compatibility notes

• Packs without Type are Content packs; nothing changes for them.
• ArtStyle is ignored by games older than 1.17.2.
• Type="Defaults" and the packages/defaults/ location are 1.20 features; on older games a Defaults pack in the flat packages/ folder still loads as an ordinary pack.
• Jobs-only packs (a package.xml plus a jobs/ folder) install since 1.17.2.