Locations System

The locations system allows you to define points of interest on a map that players can discover and interact with throughout your story.

Overview

Locations are defined as JSON files in the stories/your-story/locations/ directory. Each location appears on the map and can include:

GPS coordinates
Title and description
Visual customization (color, marker icon)
Images and reviews
Proximity radius for location-based triggers

File Structure

Basic Location

The minimal structure for a location:

json

{
  "title": "Hyde Park",
  "description": "A large park in central London",
  "latitude": 51.5073,
  "longitude": -0.1657,
  "radius": 100
}

Complete Location

A fully-featured location with all optional fields:

json

{
  "title": "The Coffee Shop",
  "description": "Where Sarah was last seen",
  "latitude": 51.5155,
  "longitude": -0.1415,
  "color": "#F97316",
  "markerIcon": "cafe-marker.png",
  "images": [
    "alex-avatar.jpg",
    "mom-avatar.jpg",
    "found-phone.png"
  ],
  "reviews": [
    {
      "author": "John Smith",
      "rating": 5,
      "text": "Great coffee and cozy atmosphere. Perfect spot for working remotely!",
      "date": "2 weeks ago"
    },
    {
      "author": "Sarah Johnson",
      "rating": 4,
      "text": "Nice place, but can get crowded during lunch hours.",
      "date": "1 month ago"
    }
  ]
}

Field Reference

Required Fields

`title`

Type: string

The name of the location as it appears on the map and in the UI.

json

"title": "The Coffee Shop"

`description`

Type: string

A brief description of the location's significance to the story.

json

"description": "Where Sarah was last seen"

`latitude`

Type: number

The latitude coordinate in decimal degrees (-90 to 90).

json

"latitude": 51.5155

`longitude`

Type: number

The longitude coordinate in decimal degrees (-180 to 180).

json

"longitude": -0.1415

Optional Fields

`color`

Type: string (hex color)

Custom color for the location marker on the map. Use hex format.

json

"color": "#F97316"

Default: Uses type-based default colors

`markerIcon`

Type: string (filename)

Custom marker icon image. File must be in stories/your-story/assets/ directory.

json

"markerIcon": "cafe-marker.png"

Default: Uses standard map pin

`radius`

Type: number (meters)

The proximity radius in meters for location-based triggers. Used with IsWithinDistance() function.

json

"radius": 100

When to use: For location-based gameplay where players need to be within a certain distance.

`initial`

Type: boolean

Whether this location is visible on the map from the start of the story.

json

"initial": true

Default: false (location must be unlocked)

`images`

Type: array of string (filenames)

Array of image filenames to display in the location details. Images must be in stories/your-story/assets/ directory.

json

"images": [
  "alex-avatar.jpg",
  "mom-avatar.jpg",
  "found-phone.png"
]

When to use: To show photos, evidence, or visual context for the location.

`reviews`

Type: array of review objects

Fake reviews to make the location feel realistic (like a business listing).

json

"reviews": [
  {
    "author": "John Smith",
    "rating": 5,
    "text": "Great coffee and cozy atmosphere!",
    "date": "2 weeks ago"
  }
]

Review object fields:

author (string) - Reviewer name
rating (number) - Star rating (1-5)
text (string) - Review text
date (string) - When the review was posted

When to use: For public places like cafes, restaurants, or businesses to add realism.

Creating Locations

Step 1: Create the JSON File

Create a new JSON file in stories/your-story/locations/ with a descriptive filename:

stories/your-story/locations/
  ├── crime-scene.json
  ├── police-station.json
  └── suspects-apartment.json

Step 2: Define the Location

Add the required fields and any optional fields you need:

json

{
  "title": "Crime Scene",
  "description": "The alley where the victim was found",
  "latitude": 51.5074,
  "longitude": -0.1278,
  "type": "objective",
  "color": "#DC2626",
  "radius": 50
}

Step 3: Reference in Ink

Use the location in your Ink scripts with the #pin tag:

ink

I found something at the crime scene. #pin:51.5074,-0.1278
You need to check this place out.

Or require the player to visit:

ink

Go to the crime scene and tell me what you find.
* [I'm there] #location_input_gps:Share your location
  ~ temp lat = GetPlayerLocationLatitude()
  ~ temp lng = GetPlayerLocationLongitude()
  ~ temp isAtScene = IsWithinDistance(lat, lng, 51.5074, -0.1278, 50)
  {isAtScene:
    Perfect! You're at the crime scene.
  - else:
    You're not close enough. Get within 50 meters.
  }

Examples

Investigation Site

json

{
  "title": "The Coffee Shop",
  "description": "Where Sarah was last seen before she disappeared",
  "latitude": 51.5155,
  "longitude": -0.1415,
  "color": "#F97316",
  "radius": 50,
  "images": [
    "coffee-shop-exterior.jpg",
    "last-known-photo.jpg"
  ],
  "reviews": [
    {
      "author": "Regular Customer",
      "rating": 5,
      "text": "Great place, but something strange happened here last week...",
      "date": "3 days ago"
    }
  ]
}

Character Home

json

{
  "title": "Sarah's Apartment",
  "description": "Where Sarah lived before she went missing",
  "latitude": 51.5074,
  "longitude": -0.1278,
  "color": "#3B82F6",
  "radius": 50,
  "initial": true
}

Background Location

json

{
  "title": "Central Park",
  "description": "A popular park in the city center",
  "latitude": 51.5073,
  "longitude": -0.1657,
  "radius": 100
}

Best Practices

Naming Files

Use descriptive, lowercase filenames with hyphens:

✅ coffee-shop.json
✅ crime-scene-alley.json
❌ Location1.json
❌ place with spaces.json

Setting Radius

Choose appropriate radius values based on location purpose:

Exact locations (buildings): 25-50 meters
Areas (parks, plazas): 100-200 meters
General areas (neighborhoods): 500+ meters

Using Colors

Use colors to indicate location importance or purpose:

Red (#DC2626) - Danger, crime scenes
Orange (#F97316) - Objectives, important locations
Blue (#3B82F6) - Story locations, character homes
Green (#10B981) - Safe locations, meeting points
Gray (#6B7280) - Background locations, points of interest

Adding Reviews

Reviews add realism to public places:

Use varied ratings (not all 5 stars)
Mix positive and negative reviews
Include subtle story hints in reviews
Use realistic dates ("2 weeks ago", "1 month ago")

Coordinates

Get accurate coordinates:

Use Google Maps or similar service
Right-click on the location
Copy the coordinates (latitude, longitude)
Use decimal format (e.g., 51.5074, -0.1278)

Unlocking Locations

Locations can be unlocked dynamically during the story using Ink tags:

ink

// Unlock a location when player discovers it
I found the place! Check your map. #unlockLocation:coffee-shop

// Unlock with a delay
The location will appear on your map in 5 minutes. #unlockLocation:crime-scene:5m

Note: Locations with "initial": true are visible from the start and don't need to be unlocked.

Integration with Location Functions

Locations work seamlessly with location-based Ink functions:

ink

EXTERNAL IsWithinDistance(lat, lng, targetLat, targetLng, radiusMeters)
EXTERNAL GetDistanceBetween(lat, lng, targetLat, targetLng)

== check_coffee_shop ==
Are you at the coffee shop?
* [Yes, I'm here] #location_input_gps:Share your GPS location
  ~ temp lat = GetPlayerLocationLatitude()
  ~ temp lng = GetPlayerLocationLongitude()
  ~ temp isNearby = IsWithinDistance(lat, lng, 51.5155, -0.1415, 50)
  
  {isNearby:
    Great! You're at the coffee shop. Look around carefully.
    -> investigate_shop
  - else:
    ~ temp distance = GetDistanceBetween(lat, lng, 51.5155, -0.1415)
    You're {distance}m away. You need to get closer.
    -> check_coffee_shop
  }

Troubleshooting

Location not appearing on map?

Check that the JSON file is in stories/your-story/locations/
Verify all required fields are present
Check for JSON syntax errors (missing commas, quotes)
Ensure initial: true or location has been unlocked

Marker icon not showing?

Verify image file is in stories/your-story/assets/
Check filename matches exactly (case-sensitive)
Ensure image is a supported format (PNG, JPG)

Location radius not working?

Verify radius is a number (not a string)
Check that radius is in meters
Use IsWithinDistance() function with matching coordinates

Reviews not displaying?

Check that all review fields are present
Verify rating is a number between 1-5
Ensure proper JSON array syntax

Next Steps

Learn about location tags: Tag Reference - Location Tags
Master location functions: External Functions - Location Functions
Test with debug tools: Debug Menu - GPS Override
See the full structure: Project Structure

Locations System ​

Overview ​

File Structure ​

Basic Location ​

Complete Location ​

Field Reference ​

Required Fields ​

title ​

description ​

latitude ​

longitude ​

Optional Fields ​

color ​

markerIcon ​

radius ​

initial ​

images ​

reviews ​

Creating Locations ​

Step 1: Create the JSON File ​

Step 2: Define the Location ​

Step 3: Reference in Ink ​

Examples ​

Investigation Site ​

Character Home ​

Background Location ​

Best Practices ​

Naming Files ​

Setting Radius ​

Using Colors ​

Adding Reviews ​

Coordinates ​

Unlocking Locations ​

Integration with Location Functions ​

Troubleshooting ​

Location not appearing on map? ​

Marker icon not showing? ​

Location radius not working? ​

Reviews not displaying? ​

Next Steps ​

Locations System

Overview

File Structure

Basic Location

Complete Location

Field Reference

Required Fields

`title`

`description`

`latitude`

`longitude`

Optional Fields

`color`

`markerIcon`

`radius`

`initial`

`images`

`reviews`

Creating Locations

Step 1: Create the JSON File

Step 2: Define the Location

Step 3: Reference in Ink

Examples

Investigation Site

Character Home

Background Location

Best Practices

Naming Files

Setting Radius

Using Colors

Adding Reviews

Coordinates

Unlocking Locations

Integration with Location Functions

Troubleshooting

Location not appearing on map?

Marker icon not showing?

Location radius not working?

Reviews not displaying?

Next Steps