====== FASERIP Online — Adding & Configuring City Buildings ======

//Last updated: February 2026 — v1.0//

//Part of the [[projects:faserip|Game Master & Artist Guide]]//

This page is a complete reference for adding, positioning, and customizing buildings on the city map. No database changes or server restarts are needed — buildings live entirely in ''game.js'' on the client side.

----

===== Table of Contents =====

  * [[#how-buildings-work|How Buildings Work]]
  * [[#the-city_buildings-object|The CITY_BUILDINGS Object]]
  * [[#building-fields-reference|Building Fields Reference]]
  * [[#map-layout-and-positioning|Map Layout and Positioning]]
  * [[#quadrant-cheat-sheet|Quadrant Cheat Sheet]]
  * [[#available-building-types|Available Building Types]]
  * [[#adding-a-custom-type|Adding a Custom Type]]
  * [[#step-by-step-example|Step-by-Step Example]]
  * [[#after-editing|After Editing]]
  * [[#tips-and-pitfalls|Tips and Pitfalls]]

----

===== How Buildings Work =====

Buildings are rendered entirely in the browser from a JavaScript data structure. When a player enters a zone, ''game.js'' reads the list of buildings for that zone and draws each one on the map canvas as a styled HTML element.

Because nothing is stored in the database, you can:

  * Add or remove buildings by editing ''game.js'' only
  * Test changes instantly with a browser refresh
  * Deploy to all players just by saving the file — no server restart needed

The file to edit is:

<code>
/var/www/html/amigaz/games/faserip/public/game.js
</code>

----

===== The CITY_BUILDINGS Object =====

Near the top of ''game.js'' you will find the ''CITY_BUILDINGS'' object. It contains one array per zone, each array holding the buildings for that zone:

<code javascript>
const CITY_BUILDINGS = {
  central_city: [
    { id: 'city-hall',    name: 'City Hall',    type: 'government', x: 100, y: 80,  icon: '🏛️', height: 160, color: '#1a4a6b' },
    { id: 'central-bank', name: 'Central Bank', type: 'bank',       x: 320, y: 60,  icon: '🏦', height: 180, color: '#1a5c2e' },
    // ... more buildings
  ],
  warehouse_district: [
    // ... buildings
  ],
  downtown: [
    // ... buildings
  ],
  industrial_zone: [
    // ... buildings
  ],
  waterfront: [
    // ... buildings
  ]
};
</code>

To add a building, insert a new line inside the correct zone's array. To remove one, delete its line. To edit one, change its field values.

----

===== Building Fields Reference =====

^ Field ^ Type ^ Required ^ Description ^
| ''id'' | string | ✅ Yes | Unique identifier. Lowercase, no spaces — use hyphens. Must be unique across ALL zones, not just within one zone. |
| ''name'' | string | ✅ Yes | The display name shown in the location panel and on hover. |
| ''type'' | string | ✅ Yes | Controls the description text players see. See [[#available-building-types|type list]] below. |
| ''x'' | number | ✅ Yes | Horizontal position in pixels from the left edge of the map. |
| ''y'' | number | ✅ Yes | Vertical position in pixels from the top of the map. This is the TOP of the building label, not the base. |
| ''icon'' | string | ✅ Yes | Any single emoji. Displayed centred on the building face. |
| ''height'' | number | ✅ Yes | Building face height in pixels. Recommended range: **60–240**. |
| ''color'' | string | ✅ Yes | Hex color code for the building face. Dark colors work best on the night background. |

==== ID Rules ====

  * Use only lowercase letters, numbers, and hyphens
  * Must be unique across every zone — even if two buildings have the same name
  * Good: ''central-bank'', ''pier-7-warehouse'', ''vex-lab-2''
  * Bad: ''Central Bank'', ''warehouse'', ''1'' (too generic), ''warehouse-1'' (if already used)

==== Color Guide ====

Buildings look best with dark, saturated base colors. The renderer automatically lightens the color for the roof and side faces.

^ Color ^ Hex Example ^ Good For ^
| Dark blue-gray | ''#1a2a4a'' | Offices, government, police |
| Dark green | ''#1a4a2a'' | Banks, parks, hospitals |
| Dark red-brown | ''#3a1a1a'' | Villain lairs, criminal buildings |
| Dark purple | ''#2a1a3a'' | Arcane, villain, underground |
| Dark steel | ''#2a2a3a'' | Industrial, factories, warehouses |
| Dark warm brown | ''#3a2a1a'' | Warehouses, markets, old buildings |
| Dark teal | ''#1a3a3a'' | Waterfront, science, media |

----

===== Map Layout and Positioning =====

The city map canvas is **900 px wide × 520 px tall**.

Two roads divide the map into four quadrants:

  * **Horizontal road** — runs across the full width at **y: 220**, occupying **y: 220 to y: 258** (38 px tall)
  * **Vertical road** — runs the full height at **x: 430**, occupying **x: 430 to x: 468** (38 px wide)

Buildings should be placed so they do **not** overlap the roads or each other.

==== Building Footprint ====

Every building occupies this space on the canvas:

  * **Width:** always **130 px** regardless of height
  * **Height:** your ''height'' value (the building face) + **22 px** (isometric roof cap) + **30 px** (label below base)
  * **Total vertical space needed:** ''height'' + 52 px

So a building with ''height: 120'' needs **172 px** of vertical clearance from its ''y'' value.

==== Safe Margins ====

Leave at least **20 px** between adjacent buildings horizontally and **10 px** between a building's base and another building's top label.

A safe horizontal gap between buildings is **150–160 px** (130 px wide + 20–30 px gap).

----

===== Quadrant Cheat Sheet =====

Use these coordinate ranges when placing new buildings to stay clear of roads:

^ Quadrant ^ X Range ^ Y Range ^ Notes ^
| Top-left | 20 – 410 | 20 – 200 | Above horizontal road, left of vertical road |
| Top-right | 480 – 880 | 20 – 200 | Above horizontal road, right of vertical road |
| Bottom-left | 20 – 410 | 270 – 440 | Below horizontal road, left of vertical road |
| Bottom-right | 480 – 880 | 270 – 440 | Below horizontal road, right of vertical road |

> **Tip:** A building at ''y: 270'' with ''height: 140'' has its label at ''y: 270 + 140 + 30 = 440''. That fits in the bottom quadrant. A height of 160 at the same y would push the label to y: 460 — still fine. Height of 200 would hit y: 500 and start to clip the map edge.

==== Suggested Starting Positions for New Buildings ====

If you just want to drop a building in quickly without thinking too hard about layout, use one of these open slots. They are gaps in the default building placement across all zones:

^ Slot ^ X ^ Y ^ Height Limit ^
| Top-left corner | 20 | 30 | 160 |
| Top-right corner | 740 | 30 | 160 |
| Mid top-left | 200 | 30 | 150 |
| Mid top-right | 580 | 30 | 150 |
| Bottom-left corner | 20 | 280 | 140 |
| Bottom-right corner | 740 | 280 | 140 |
| Bottom-centre-left | 200 | 280 | 140 |
| Bottom-centre-right | 580 | 280 | 140 |

----

===== Available Building Types =====

The ''type'' field controls the description text shown in the location panel when a player clicks the building. It also controls which description is shown in investigation results.

These types are defined in the ''LOCATION_DESCRIPTIONS'' object in ''game.js'':

^ Type ^ Description Shown to Players ^
| ''government'' | The seat of city government. Heroes come here for official sanctions and briefings. |
| ''bank'' | A major financial institution. Frequent target for supervillain attacks. |
| ''police'' | Law enforcement HQ. Coordinate with officers and get mission intel. |
| ''hospital'' | Emergency medical center. Protect civilians and access healing supplies. |
| ''warehouse'' | Old storage facility — popular hideout for criminals and stolen goods. |
| ''villain-lair'' | Something sinister lurks here... A hero should proceed with caution. |
| ''criminal'' | Clearly illegal operations. Shut it down! |
| ''commercial'' | Shopping and entertainment. Lots of civilians to protect. |
| ''factory'' | Industrial facility with hazardous materials. Dangerous environment. |
| ''docks'' | Cargo shipping area. Smuggling is rampant here. |
| ''office'' | Corporate headquarters. Business dealings — some above board, some not. |
| ''landmark'' | An iconic city landmark. Worth protecting at all costs. |
| ''media'' | Local news station. They will cover your heroic deeds — or your failures. |
| ''education'' | A center of knowledge. Research villain weaknesses here. |
| ''science'' | Advanced research facility. Unknown experiments underway. |
| ''sports'' | City sports arena. Packed with civilians on game days. |
| ''hotel'' | Luxury hotel. Frequently used by visiting villains as a base of operations. |
| ''transport'' | Transportation hub. Excellent for cutting off villain escape routes. |
| ''utility'' | City power grid. A prime target for villains wanting to plunge the city into darkness. |
| ''underground'' | Access to the city's underground network. Danger unknown. |
| ''junkyard'' | Salvage yard. Useful for improvised equipment — if you can fight off the gangs. |
| ''market'' | Busy market district. Civilians everywhere. Collateral damage is a concern. |
| ''restaurant'' | Dining district. Keep innocent bystanders out of harm's way. |
| ''residential'' | Apartment buildings. Civilians live here — protect them at all costs. |
| ''plaza'' | Open public space. Great for large-scale battles away from buildings. |

----

===== Adding a Custom Type =====

If none of the existing types fit your building, add your own in two steps.

**Step 1** — Add your type to ''LOCATION_DESCRIPTIONS'' near the top of ''game.js'':

<code javascript>
const LOCATION_DESCRIPTIONS = {
  // ... existing entries ...
  'casino':    'Glittering lights hide a web of criminal connections. The house always wins.',
  'subway':    'Underground transit hub. Fast travel — and a perfect ambush point.',
  'safehouse': 'A secret hero refuge. Rest, regroup, and plan your next move here.',
};
</code>

**Step 2** — Use your new type in a building entry:

<code javascript>
{ id: 'lucky-casino', name: "Lucky's Casino", type: 'casino', x: 480, y: 30, icon: '🎰', height: 130, color: '#2a1a0a' }
</code>

That's all. The description will automatically appear in the location panel when players click the building.

----

===== Step-by-Step Example =====

This example adds three new buildings to the Warehouse District: a pawn shop, a hero safe house, and a villain underground HQ.

==== 1. Open the file ====

<code bash>
nano /var/www/html/amigaz/games/faserip/public/game.js
</code>

==== 2. Find the warehouse_district array ====

Use Ctrl+W in nano to search for ''warehouse_district''.

==== 3. Add the new buildings ====

<code javascript>
warehouse_district: [
  { id: 'warehouse-1',    name: 'Old Warehouse',     type: 'warehouse',    x: 80,  y: 100, icon: '📦', height: 100, color: '#3a3a2a' },
  { id: 'warehouse-2',    name: 'Storage Depot',     type: 'warehouse',    x: 310, y: 140, icon: '📦', height: 90,  color: '#3a3a2a' },
  { id: 'warehouse-3',    name: 'Cold Storage',      type: 'warehouse',    x: 540, y: 110, icon: '🧊', height: 105, color: '#2a3a4a' },
  { id: 'chop-shop',      name: 'Chop Shop',         type: 'criminal',     x: 160, y: 290, icon: '🔧', height: 85,  color: '#3a2a1a' },
  { id: 'hideout',        name: 'Abandoned Factory', type: 'villain-lair', x: 420, y: 270, icon: '💀', height: 130, color: '#2a1a3a' },
  { id: 'rail-yard',      name: 'Rail Yard',         type: 'transport',    x: 620, y: 310, icon: '🚂', height: 75,  color: '#2a2a2a' },
  // ---- NEW ----
  { id: 'pawn-shop',      name: "Lucky's Pawn Shop", type: 'criminal',     x: 740, y: 30,  icon: '💍', height: 80,  color: '#2a2a1a' },
  { id: 'safe-house',     name: 'Hero Safe House',   type: 'safehouse',    x: 20,  y: 280, icon: '🛡️', height: 95,  color: '#1a3a2a' },
  { id: 'underground-hq', name: 'Underground HQ',    type: 'villain-lair', x: 740, y: 280, icon: '☠️', height: 110, color: '#1a0a2a' },
],
</code>

> Note: ''safe-house'' uses type ''safehouse'' — a custom type. If you want a description, add it to ''LOCATION_DESCRIPTIONS'' first (see [[#adding-a-custom-type|Adding a Custom Type]] above).

==== 4. Save the file ====

In nano: **Ctrl+O**, Enter, **Ctrl+X**

==== 5. Test it ====

Go to your browser, navigate to the game, and press **Ctrl+Shift+R** to hard-refresh. The new buildings will appear immediately.

----

===== After Editing =====

  * **No server restart needed** — buildings are client-side only
  * **Hard refresh required** — press Ctrl+Shift+R (or Cmd+Shift+R on Mac) to bypass the browser cache
  * **All players must refresh** — other players already in the game will see the old map until they refresh
  * If a building doesn't appear, check the browser console (F12) for JavaScript errors — usually a missing comma or duplicate ''id''

==== Common Errors ====

^ Symptom ^ Likely Cause ^
| Building doesn't appear | Missing comma after the previous entry, or a typo in the field names |
| All buildings disappear | JavaScript syntax error — open browser console (F12) and look for the error line |
| Building appears in wrong place | x/y values swapped, or forgetting that y increases downward |
| Location panel shows no description | The ''type'' value doesn't match any key in ''LOCATION_DESCRIPTIONS'' |
| Two buildings overlap | x values too close together — increase spacing by at least 150 px |

----

===== Tips and Pitfalls =====

  * **Always check the browser console after editing.** A single missing comma will break the entire map. The console will tell you exactly which line.
  * **Keep a backup.** Before editing, run ''cp game.js game.js.bak'' so you can restore quickly.
  * **Sketch your layout first.** Draw the 900×520 grid on paper or in a drawing app. Mark the roads at x:430 and y:220. Sketch where you want buildings before committing positions in code.
  * **Tall buildings push down.** A building with ''height:200'' at ''y:270'' will have its label at y:500 — nearly off the bottom of the map. Keep tall buildings in the top quadrants where there's more vertical space.
  * **Villain lairs look best with dark purples.** Colors like ''#1a0a2a'' or ''#2a0a3a'' give them a sinister look that stands out from the rest of the city.
  * **The ''id'' field is used in CSS selectors.** If a mission highlights a building (the glow effect), it looks up the element by ''data-building-id''. If two buildings share an id, only the first one will glow.
  * **Add buildings to match your missions.** If you write a mission set at "The Apex Arena", add an arena building to the relevant zone first so players can click on it.

----

//See also: [[projects:faserip|Game Master & Artist Guide]] — [[projects:faserip#creating-missions|Creating Missions]] — [[projects:faserip#art-replacement-guide|Art Replacement Guide]]//