Towny Integration

Towny Integration

Division of responsibility

	Responsibility
TerraForge	terrain, geography, coordinates, distances
Towny	towns, claims, nations, residents, permissions
Players	building everything

TerraForge never creates a town, claims a plot or places a block. It annotates the towns players create with real-world geography.

Requirements

Towny installed, towny.enabled: true in terraforge.yml. Towny is a soft dependency: without it the module is not loaded and the rest of TerraForge is unaffected.

What it adds

TerraForge resolves and stores, per town: latitude/longitude of the spawn, elevation, country and region. Stored in the town_geography table, keyed by town UUID. Towny's own data is never modified.

The annotation is kept in step with Towny by observing four events, all at MONITOR priority — TerraForge never influences whether a town is created, moved or deleted:

Event	Effect
NewTownEvent	annotate the new town
TownSetSpawnEvent	re-annotate: a moved spawn changes coordinates, country and elevation
RenameTownEvent	write the new display name through
DeleteTownEvent	forget the town

Backfilling existing towns

Towns that already existed before TerraForge was installed have no annotation, because no event ever fired for them:

/earth towny refresh          # every town Towny knows
/earth towny refresh Berlin   # one town
/earth towny status           # how many writes are still queued

Requires terraforge.command.towny (op by default). A town without a spawn is skipped.

Threading

Reading Towny is a main-thread operation; writing SQLite is a disk write and must not be. The town is snapshotted on the server thread into a plain record, and only that record crosses to a single writer thread that owns one connection — writes keep their order, so a rename followed by a delete can never land the other way round.

/earth towny refresh over a large server returns immediately and drains in the background; /earth towny status shows the backlog.

What it deliberately does not do

• no automatic town creation
• no automatic claims
• no generated buildings or roads for towns
• no changes to Towny's economy, permissions or war rules

---

See also: BlueMap Integration · Commands