Add coordinate system documentation

Signed-off-by: Graham <gpe@openrs2.org>
Graham 4 years ago
parent f099972bee
commit b3b46bee1a
  1. 111
      share/doc/coordinate-system.md
  2. 8
      share/doc/glossary.md

@ -0,0 +1,111 @@
# Coordinate system
## Summary
| Name | Levels | Width (tiles) | Height (tiles) |
|------------------------|-------:|--------------:|---------------:|
| World | 4 | 16384 | 16384 |
| Area | 1 or 4 | 104 | 104 |
| MapSquare | 4 | 64 | 64 |
| MapSquare (underwater) | 1 | 64 | 64 |
| Viewport (?) | 1 | 32 | 32 |
| Zone | 1 | 8 | 8 |
## Introduction
RuneScape is a three-dimensional tile-based world. The entire world is made up
of 16384x16384 tiles on 4 levels of elevation (ranging from `0` to `3`
inclusive), including the ground level. The X and Z axes range from `0` to
`16383` inclusive.
The Y axis represents the level of elevation, with `0` representing ground
level. The X and Z axes represent coordinates on the plane - when the world map
or mini map is plotted in two dimensions, the X axis is the horizontal axis
(with X increasing from left to right), and the Z axis is the vertical axis
(with Z increasing from bottom to top).
## Map squares
The world is split into map squares, each of which contains 64x64 tiles across
4 levels. Map squares are the granularity of the maps stored in the client's
cache.
Each map square has up to five files in the client's cache:
| File name | Name | Description |
|-----------|-----------------|-----------------------------------------------------------------------|
| `mX_Z` | Map | Contains floor underlays, overlays, tile heights and flags |
| `lX_Z` | Locs | Contains locs (walls, wall decoration, scenery and ground decoration) |
| `umX_Z` | Underwater map | Contains underwater equivalent of the map file |
| `ulX_Z` | Underwater locs | Contains underwater equivalent of the locs file |
| `nX_Z` | NPC spawns | Contains NPC spawns for the animated login screen |
The underwater files contain a single virtual `-1` level used to represent the
tiles and locs that can be seen beneath translucent water tiles in HD mode. The
server does not interact with this level, it purely exists for decorative
purposes.
The X and Z coordinates of a map are the coordinates of the origin tile divided
by 64. Internally, the client combines these two values into a single ID by
calculating `(X << 8) | Z`.
## Zones
Each map square is split into zones, each of which contains 8x8 tiles across a
single level. Zones are the granularity used for most packets that interact with
the world - for example, spawning locs and obj stacks. An entire zone may be
reset and populated with dynamic locs and obj stacks in one packet.
Zones are also the granularity used to build instances, such as player-owned
houses.
The left-hand side of the world (for tiles ranging from X=0 to X=6399 inclusive)
is used for the static map squares stored in the cache. The right-hand side of
the world (for tiles from X=6400 above) is used for instances, which are
dynamically constructed by copying zones from the left side of the world and
moving/rotating them.
## Dungeons
Dungeons are typically, but not always, 6400 Z units above the equivalent
ground-level areas. 6400 was likely chosen as this corresponds to 100 map
squares, meaning a single `1` digit needs to be added to or removed from the
map's file name to switch between ground level and the corresponding dungeon.
## Area
The area represents the 104x104 group of tiles (or 13x13 group of zones) held in
the client's memory. Depending on its settings, the client only retains the
player's current level or retains all four levels.
The area is always zone-aligned. When the area is initially built, it is centred
around the player's current zone.
When the player is within 16 tiles of the edge of the current area, it is
rebuilt.
## Viewport
The viewport (note: unlike the other names in this document, we do not know the
official Jagex name) is the 32x32 group of tiles, always centred around the
current player, within which other players and NPCs are visible. Players can
only see other players and NPCs on the same level as them.
## Coordinates
When used in a script, the coordinates of a tile are packed into a 32-bit
integer as follows:
| **Field** | (unused) | Level | X | Z |
|-----------|----------|------:|---:|---:|
| **Bits** | 2 | 2 | 14 | 14 |
The two unused bits are set to zero.
Literals in scripts are represented with the X and Z coordinates split into the
map coordinates and the local coordinates within each map:
`<level>_<map_x>_<map_z>_<x>_<z>`. For example, (0, 3094, 3107) is written as
`0_48_48_22_35` in a script.
The teleport command uses a similar syntax:
`::tele <level>,<map_x>,<map_z>,<x>,<z>`.

@ -3,9 +3,10 @@
| Jagex name | RSPS community name(s) | Description | | Jagex name | RSPS community name(s) | Description |
|-------------------|------------------------|------------------------------------------------------------------------------| |-------------------|------------------------|------------------------------------------------------------------------------|
| | V1 | A middle-endian byte order used on [Honeywell Series 16][hs16] computers | | | V1 | A middle-endian byte order used on [Honeywell Series 16][hs16] computers |
| | Viewport | A 1x32x32 group of tiles (inside which other players and NPcs are visible) |
| Alt3 | V2 | A middle-endian byte order used on [PDP-11][pdp11] computers | | Alt3 | V2 | A middle-endian byte order used on [PDP-11][pdp11] computers |
| Ap | | An op that trigers when you approach (rather than reach) the target | | Ap | | An op that trigers when you approach (rather than reach) the target |
| Area | | A 104x104x4 group of tiles | | Area | | A 104x104 group of tiles (held in memory by the client) |
| BAS | Stance | Base animation set | | BAS | Stance | Base animation set |
| CS1 | | Client script version 1 | | CS1 | | Client script version 1 |
| CS2 | | Client script version 2 | | CS2 | | Client script version 2 |
@ -23,7 +24,7 @@
| JS5 | | Jagex store version 5? | | JS5 | | Jagex store version 5? |
| Loc | Object | | | Loc | Object | |
| MSI | | Map scenery icon | | MSI | | Map scenery icon |
| MapSquare | Map | A 64x64x4 group of tiles | | MapSquare | Map | A 4x64x64 group of tiles (the granularity of map files in the cache) |
| Mel | | Map element | | Mel | | Map element |
| Modal | | An interface that can be (manually or automatically) closed by the client | | Modal | | An interface that can be (manually or automatically) closed by the client |
| MultiLoc | | Transforms a loc into another based on a varp or varbit | | MultiLoc | | Transforms a loc into another based on a varp or varbit |
@ -37,6 +38,7 @@
| Param | | A key used to add a extra attributes to locs, NPCs, objs and structs | | Param | | A key used to add a extra attributes to locs, NPCs, objs and structs |
| PathingEntity | Character, Entity, Mob | A player or NPC | | PathingEntity | Character, Entity, Mob | A player or NPC |
| ProjAnim | Projectile | | | ProjAnim | Projectile | |
| Region | Instance | |
| ScriptVarType | | An enum representing types that can be used in a client script | | ScriptVarType | | An enum representing types that can be used in a client script |
| Seq | Animation | Sequence | | Seq | Animation | Sequence |
| Skill | Skill | A type of skill | | Skill | Skill | A type of skill |
@ -51,7 +53,7 @@
| Varc | | Client variable | | Varc | | Client variable |
| Varcstr | | Client string variable | | Varcstr | | Client string variable |
| Varp | Config | Player variable | | Varp | Config | Player variable |
| Zone | Region | An 8x8x1 group of tiles | | Zone | Region, Chunk | A 1x8x8 group of tiles (the granularity used by various packets) |
## Loc layers ## Loc layers

Loading…
Cancel
Save