From b3b46bee1a0052a50a6216fe6b7c602cb3eb8116 Mon Sep 17 00:00:00 2001 From: Graham Date: Sat, 23 Jan 2021 13:26:18 +0000 Subject: [PATCH] Add coordinate system documentation Signed-off-by: Graham --- share/doc/coordinate-system.md | 111 +++++++++++++++++++++++++++++++++ share/doc/glossary.md | 8 ++- 2 files changed, 116 insertions(+), 3 deletions(-) create mode 100644 share/doc/coordinate-system.md diff --git a/share/doc/coordinate-system.md b/share/doc/coordinate-system.md new file mode 100644 index 00000000..290c6071 --- /dev/null +++ b/share/doc/coordinate-system.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: +`____`. For example, (0, 3094, 3107) is written as +`0_48_48_22_35` in a script. + +The teleport command uses a similar syntax: +`::tele ,,,,`. diff --git a/share/doc/glossary.md b/share/doc/glossary.md index c8814e2d..eaffe6cd 100644 --- a/share/doc/glossary.md +++ b/share/doc/glossary.md @@ -3,9 +3,10 @@ | Jagex name | RSPS community name(s) | Description | |-------------------|------------------------|------------------------------------------------------------------------------| | | 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 | | 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 | | CS1 | | Client script version 1 | | CS2 | | Client script version 2 | @@ -23,7 +24,7 @@ | JS5 | | Jagex store version 5? | | Loc | Object | | | 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 | | 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 | @@ -37,6 +38,7 @@ | Param | | A key used to add a extra attributes to locs, NPCs, objs and structs | | PathingEntity | Character, Entity, Mob | A player or NPC | | ProjAnim | Projectile | | +| Region | Instance | | | ScriptVarType | | An enum representing types that can be used in a client script | | Seq | Animation | Sequence | | Skill | Skill | A type of skill | @@ -51,7 +53,7 @@ | Varc | | Client variable | | Varcstr | | Client string 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