Talad: Created page with "= CityManager admin guide = CityManager uses database tables to define cities, their manager NPCs, development tiers, required resources, and buildable assets. Apply configuration changes while the server is stopped, then restart it and reconnect the client. CityManager loads its configuration at startup and updates progress during play. == 1. Define the city and manager NPC == Create or choose an existing, normally spawned NPC in the `characters` table. A..."

2026-09-13T16:19:05Z

Created page with "= CityManager admin guide = CityManager uses database tables to define cities, their manager NPCs, development tiers, required resources, and buildable assets. Apply configuration changes while the server is stopped, then restart it and reconnect the client. CityManager loads its configuration at startup and updates progress during play. == 1. Define the city and manager NPC == Create or choose an existing, normally spawned NPC in the <code>characters</code> table. A..."

New page

= CityManager admin guide =

CityManager uses database tables to define cities, their manager NPCs, development tiers, required resources, and buildable assets.

Apply configuration changes while the server is stopped, then restart it and reconnect the client. CityManager loads its configuration at startup and updates progress during play.

== 1. Define the city and manager NPC ==

Create or choose an existing, normally spawned NPC in the <code>characters</code> table. Assign its <code>characters.id</code> to <code>city_info.npc_manager_id</code>.

The NPC becomes a city manager automatically when it loads. No separate CityManager flag or dialogue is required by this module. Use a different NPC for each city: an NPC is associated with only the first matching city.

Add one row to '''city_info''':

{| class="wikitable"
! Column
! What to enter
|-
| <code>id</code>
| Unique positive city ID, referenced by the other city tables.
|-
| <code>name</code>
| City display name.
|-
| <code>location</code>
| City center as integer <code>x,y,z</code> coordinates in Unreal world units (centimeters), for example <code>205238,-310363,11061</code>.
|-
| <code>influence_range</code>
| Base radius in meters. The effective radius is this value multiplied by the current Infrastructure tier. Tier 0 gives a zero radius.
|-
| <code>npc_manager_id</code>
| The manager NPC's <code>characters.id</code>. The NPC must actually load into the world.
|-
| <code>citizens</code>
| Base population. The displayed population is calculated from this value and the current tiers.
|-
| <code>happiness</code>
| Normally <code>0.5</code>. The server recalculates happiness from the current tiers, overriding this loaded value.
|-
| <code>period_start_date</code>
| Leave <code>NULL</code> for a new city. The current module does not implement a ranking-period reset using this field.
|-
| Six <code>cat_*</code> columns listed below
| Current achieved tier: normally <code>0</code> for a new city, or <code>1</code>–<code>3</code> for an established city.
|}

Players must target the manager and be within 1,000 Unreal units (10 meters) to request the city information screen.

== 2. Define categories and tier descriptions ==

Use these category IDs in the development tables:

{| class="wikitable"
! Category ID
! Category
! Current tier column in city_info
|-
| 1
| Infrastructure
| <code>cat_infrastructure</code>
|-
| 2
| Hospitality
| <code>cat_hospitality</code>
|-
| 3
| Crafting
| <code>cat_crafting</code>
|-
| 4
| Faith
| <code>cat_faith</code>
|-
| 5
| Education
| <code>cat_education</code>
|-
| 6
| Agriculture
| <code>cat_agriculture</code>
|}

The data model reserves <code>-1</code> to hide an unavailable category. However, the current population and happiness calculations still include negative tier values. Avoid <code>NULL</code> tiers.

Add one row per city, category, and target tier to '''city_tier_def''':

{| class="wikitable"
! Column
! What to enter
|-
| <code>city_id</code>
| The city's <code>city_info.id</code>.
|-
| <code>city_category</code>
| Category ID from 1 to 6.
|-
| <code>tier</code>
| The achieved tier being described, normally 1, 2, or 3.
|-
| <code>description</code>
| Player-facing explanation of that tier's benefits.
|}

Descriptions are display text. Adding a benefit to a description does not implement that benefit.

The module calculates:
* Population: base population plus 10% of the base for each summed tier in Infrastructure, Crafting, and Agriculture.
* Happiness: <code>0.5 + round((Hospitality + Faith + Education) × 0.055, 2)</code>.

== 3. Define resources required for each tier ==

Each resource must have an existing definition in '''item_stats'''. CityManager obtains the resource name and image from that definition.

Add one row per required resource to '''city_resource_tiers''':

{| class="wikitable"
! Column
! What to enter
|-
| <code>city_id</code>
| The city's <code>city_info.id</code>.
|-
| <code>tier</code>
| The '''target tier''': 1 pays for the upgrade from 0 to 1; 2 pays for 1 to 2; 3 pays for 2 to 3.
|-
| <code>city_category</code>
| Category ID from 1 to 6.
|-
| <code>item_stats_id</code>
| The required resource's <code>item_stats.id</code>. This references an item definition, not an individual item instance.
|-
| <code>need</code>
| Positive whole-number quantity required.
|-
| <code>storage</code>
| Amount already donated. Initialize to <code>0</code>; the server updates it during play.
|}

Several rows for the same city, category, and tier mean '''all those resources are required'''.

Keep each combination of <code>city_id</code>, <code>city_category</code>, <code>tier</code>, and <code>item_stats_id</code> unique. The supplied schema does not enforce this.

Define resource costs for every supported target tier of each enabled category. Missing rows should not be used to disable an upgrade: the current server upgrade check can succeed without matching requirements and does not itself enforce a tier-3 cap.

=== Example ===

Assuming city ID <code>10</code> already exists, these rows make Infrastructure tier 1 require 10 units of item 8072 and 2,000 units of item 86:

<pre>
INSERT INTO city_resource_tiers
(city_id, tier, city_category, item_stats_id, need, storage)
VALUES
(10, 1, 1, 8072, 10, 0),
(10, 1, 1, 86, 2000, 0);

INSERT INTO city_tier_def
(city_id, city_category, tier, description)
VALUES
(10, 1, 1,
'City influence reaches the base radius; population gains 10% of its base.');
</pre>

Verify the item IDs in your database before using this example. Then add costs and descriptions for tiers 2 and 3 and repeat for the other enabled categories.

=== Donations and upgrades ===

* The server checks for an upgrade after a contribution.
* Every required resource must have <code>storage == need</code>. Avoid overfilling storage.
* On upgrade, the completed tier's resource storage resets to zero and the corresponding <code>city_info.cat_*</code> value increases.
* Preloading storage alone does not trigger an upgrade at startup.
* For money, use the item definition named exactly <code>Tria</code>. The amount is taken from the player's wallet in trias. The seed scripts use item ID 86; verify this locally.
* Ordinary donations match the item definition and name, exclude equipped items, and require a single sufficient stack per submitted donation.

== 4. Optional buildable assets ==

Assets use separate definitions and recipes:

{| class="wikitable"
! Table
! What to add
|-
| <code>city_asset_def</code>
| One row per asset: unique <code>asset_id</code>, <code>asset_category</code>, and <code>item_stats_id</code> for the finished asset's name and description.
|-
| <code>city_asset_resources_def</code>
| One row per recipe ingredient: <code>asset_id</code>, resource <code>item_stats_id</code>, and positive <code>need</code>.
|-
| <code>city_asset_mapping</code>
| Availability in a city: <code>city_id</code>, development <code>category</code> (1–6), required <code>tier</code>, and <code>asset_id</code>.
|}

Use these values for '''city_asset_def.asset_category''':

{| class="wikitable"
! Asset category ID
! Asset group
|-
| 7
| Defense
|-
| 8
| Army
|-
| 9
| Siege
|-
| 10
| Magic
|}

The SQL schema comment saying asset categories are 1–4 is outdated.

Asset categories and development categories have different purposes. For example, an asset with <code>asset_category = 7</code> and a mapping with <code>category = 1, tier = 2</code> is a Defense asset associated with Infrastructure tier 2.

Add the asset's ingredient rows separately and avoid duplicate mappings or recipe ingredients.

== 5. Progress tables and decay ==

For a new city, normally leave these tables without rows for that city. The server creates progress during play. The tables themselves must still exist.

{| class="wikitable"
! Table
! Fields
! Purpose
|-
| <code>city_consume_status</code>
| <code>city_id, tier, city_category, consumption</code>
| Remaining tier lifetime, starting at 1 and decreasing toward 0.
|-
| <code>city_assets_resource_storage</code>
| <code>city_id, asset_id, item_stats_id, storage</code>
| Ingredients donated toward an unfinished asset.
|-
| <code>city_assets_storage</code>
| <code>city_id, asset_id, quantity</code>
| Completed asset counts.
|-
| <code>city_ranking</code>
| <code>city_id, guild_id, character_id, points</code>
| Contributor scores.
|}

Tier-resource donations are stored directly in <code>city_resource_tiers.storage</code>.

Decay is configured globally in <code>Config/DefaultServerConfig.ini</code>:

<pre>
[/script/PSUnreal.CityManager]
cityConsumeTime=60
cityConsumeAmount=0.1
</pre>

These checked-in settings schedule a tick every 60 seconds. Each tick decreases an existing current-tier consumption entry by 0.1. A missing entry is first created at 1.

When consumption reaches zero or below, the category drops one tier. This is a remaining-lifetime counter, rather than a periodic subtraction of individual stored ingredients.

== 6. Verify the setup ==

# Restart the server and reconnect the client.
# Check startup logs for invalid city, item, or asset references.
# Target the manager within 10 meters and open the city information screen.
# Verify the city name, categories, next-tier costs, and descriptions.
# Make a donation and complete one tier. Confirm that its tier increases and its resource storage resets.
# If assets are configured, verify their required-tier availability and recipes in the client.

This guide is based on <code>Source/PSUnreal/server/citymanager.cpp</code>, <code>citymanager.h</code>, NPC registration in <code>pscharacter.cpp</code>, and the schema in <code>Scripts/psunreal_mysql_20260724.sql</code>. It has not been validated against a running database.

The older <code>Scripts/UPDATE_SCHEMA_PSUNREAL_CITY.sql</code> omits <code>city_tier_def</code>. The seed data is an example and does not provide a complete setup for every city.

City Manager - Revision history