====== Place File Synax ======

[[Place Files]]

===== Overview =====

Place files contain:

  * A Header consisting of one or more Header Lines.
  * Areas (or Libraries) which serve as namespaces containing:
    * Locations (each has a mandatory prefix of either Int. or Ext.)
      * Some Locations may be logically treated as Main Locations comprised of Sub-Locations.
      * If a slash is present in a Location name, it separates the Main Location from the Sub-Location.
    * Camera Angles (Named with A-Z,0-9,_)
    * Package Definitions

==== Header Line ====

This line must begin with #, and may include any text desired.
There must be at least one header line, but the file may include as many as are deemed useful for documentation purposes.

<code>
# Place file for Project Name
</code>

==== Comments ====

Comments may be included anywhere in the .place file:

<code>
; Any line beginning with a semicolon is a comment.
</code>

-----

===== Importing Content from Other Files =====

==== IMPORT FROM / IMPORT ALL ... FROM ====

When a library is imported, its contents becomes available for use elsewhere in the Place File, but they are conceptually still stored in the library, and don't get compiled in with your game until you make use of them individually.  If you import a location specifically, it gets incorporated into your project immediately (you can still open its definition back up to make modifications, however.)  A package is a named set of connected locations

<code>
IMPORT [LIBRARY | LIBRARIES] FROM "filename":
  "BUILDINGS" AS "B"
  "NATURE" AS "N"
  "BUILDINGS" LOCATION "INT. CAFE" [AS "INT. DINER"]
</code>

or

<code>
IMPORT ALL LIBRARIES FROM "filename" [PREFIXED BY "IMPORTED"]
</code>

==== [FROM ...] ====

When you see [FROM ...] (but not FROM "filename") as part of other syntax, it means you may optionally specify a Library or Area from which the preceding named object should be fetched.

<code>
[FROM LIBRARY "L" | FROM AREA "A"]
</code>

==== (BASED ON) ====

This must be the first line after an Area Declaration or after a Location Header.

When used for an Area:
<code>
   MY NEW AREA
   -- --- ----
(BASED ON "AREA OR LIBRARY NAME" [IMPORTED FROM "filename"] [ROTATE 0])
</code>

When used for a Location, it makes a copy of the named Location and opens it for modification.  This Location may either be a Location that already exists in your game, or a Location defined in an imported Library:

<code>
INT. MY NEW LOCATION
(BASED ON "INT. LOCATION NAME" [FROM ...] [ROTATE 0])
</code>

When used for a Camera, it makes a copy of the named Camera and opens it for modification. This Camera may either be a Camera that already exists in your game, or a Camera defind in an imported Library:

<code>
CAMERA: OFFICE
(BASED ON "OFFICE" [FROM ...])
</code>

==== REFER TO IMPORTED ... AS ... ====

Goes after the (BASED ON) line for an Area, this is used to effectively rename any Package, Location, or other identifier from the imported place file so that a different name is applied throughout the imported version of the content.

<code>
REFER TO IMPORTED "POLICE STATION" AS "SHERIFF'S DEPARTMENT"
</code>

-----

===== Packaging Sets of Locations =====

==== PACKAGE ====

Packaging Locations together allows them to be imported or cloned as a related set, maintaining any connections between the exits of the various locations.  All Cameras associated with the Locations are also automatically included in the package.

<code>
PACKAGE "TRAIL" (START):
  EXT. TRAILHEAD ([FROM ...] AS $START)
  WITHIN $PACKAGE:
  EXT. TRAIL / SWITCHBACK PATH
  EXT. TRAIL / LARGE ROCK
  EXT. TRAIL / MEADOW
</code>

==== UNPACK ====

<code>
UNPACK "TRAIL" [FROM ["filename.place"] [LIBRARY "OUTDOORS"]]
  AS "NATURE PATH" (START = "PARKING LOT")
</code>

-----

===== Location Definitions ======
==== LOCATION DEFAULTS: ====

This opens up the template for locations defined within this Library or Area that aren't BASED ON any other location. Once this line is encountered, you are in "Location Definition Context" until switching to another context.

<code>
LOCATION DEFAULTS:

A-CAM:  $FILENAME($LOCATION), Default($FILENAME($LOCATION))
</code>

==== INT. / EXT. ====

Name a Location in uppercase on an unindented line to either create it (if new) or re-open its definition for additions, changes, or deletions.  Once this line is encountered, you are in "Location Definition Context" until switching to another context.

<code>
INT. OFFICE
</code>

==== Descriptive Text ====

To add or replace a description:

<code>
INT. OFFICE

  You are in a poorly lit, smoke-filled office.  In the center of the
  room is a heavy, well-worn mahogany desk.
</code>

To append to the existing description:

<code>
INT. OFFICE

  You look around to gain your bearings. $DESCRIPTION
</code>

or

<code>
DELETE DESCRIPTION
</code>

==== MARK / DELETE MARK ====

To add or update a mark in the current Location:

<code>
MARK markname
</code>

To delete an existing mark:

<code>
DELETE MARK markname
</code>

==== x-CAM / DELETE x-CAM ====

This is how to assign cameras to a location.  You can use $A-CAM, $B-CAM, etc, to refer to the previously defined value of any CAM.

Note that the same Camera Angle can be assigned to multiple named CAMs, which may be useful (for example) if the coverage area is wider than what had originally been envisioned.

If a camera includes visibility of other locations, pass those location names in parenthesis as named parameters to the Camera Angle.

If the current Location is not the primary subject of the desired camera, you may use POV and the primary Location name to treat that Location as primary, and then list which of the Camera Angle's named parameters the current Location should be passed into (it will be automatically filled in with this current Location's name, which doesn't need to be written in.)

Note also that each CAM designation may list more than one Camera Angle.  If the game is going to be rendered with more than one rendering engine (i.e., fully 3D vs. Visual Novel style), or if the designatd Camera Angle is disqualified for some other reason (i.e., not supporting a night-time view when the current time is night), then the first available/eligible camera in the list will be used when the given CAM is called for.

When a location is shown in a scene, and no specific camera angle is specified, the lowest-lettered available camera will be used (usually A-CAM.)

<code>
A-CAM: OFFICE
B-CAM: OFFICE_REVERSE(HALL = "Ext. Office"), $A-CAM
C-CAM: POV "Ext. Office" OUTSIDE_OFFICE(INTERIOR), OFFICE
</code>

To delete an existing CAM definition from this location:

<code>
DELETE C-CAM
DELETE OFFICE_REVERSE FROM B-CAM
</code>

==== @(EXIT) / DELETE @(EXIT) ====

Defines, edits, or deletes exits in the current location.

Exits can be a simple direction or a named target:

Simple directions include the abbreviated compass directions (N, NNE, NE, ENE, E, ESE, SE, SSE, S, SSW, SW, WSW, W, WNW, NW, NNW), UP, or DOWN.

Target names may not include spaces.

Locations may be substantially abbreviated.  Int. or Ext. alone will flip to the corresponding exterior or interior matching with the current location (if any.)  If a location has a main area and sub-areas (separated by a slash), and it is within the same main area as the current location, only the sub-area needs to be given.

After a location, flags may be given in parenthesis.  These flags help the Ghostwood Engine to verify the integrity and sensibility of your location definitions.  If either end of a connected route contains the flag "WINDING", the game engine doesn't care if the return direction is at variance with the arrival direction.  And, if the origin route has the flag "ONE WAY", then no return route is expected.

<code>
  DELETE @N
  @NW Ext. BACK ALLEY (WINDING)
  @DOOR Int. (ONE WAY)
</code>