---
# System prepended metadata

title: Overmaps

---

# Overmaps

## Frontend Implementation
- This consists of everything players would care about.
- Read this and not backend if you have no interest in the nitty gritty (and actually fun/hard part).

### Entities
- /datum/overmap_entity/static
    - For things like planets, main ships/major things that won't feasibly dock anywhere
- /datum/overmap_entity/landable
    - For things like shuttles, which are primarily used to dock at static destinations.
- All overmap entities are a subtype of /datum/overmap_object/movable.
- Entities will be ticked by the same timings that tick objects, to synchronize effects with physics.

### Ships
- When I say "ship", this also includes planets
- Identified by an unique string
- Mass, are movable objects, etc, size.
- Control columns which are indestructible for non custom shuttles (perhaps custom shuttles should have an indestructible, non-dense control core or all ships should), bitflags for what they control of each ship module.
    - Physical object. Someone with access to it can do things like reprogram docking codes
    - Each module/thruster/etc will **also** have physical settings. You should be able to operate the ship via radio if needed. The control system is just a centrallized abstraction that makes piloting easier.
- Ship modules:
    - Weapons
    - Shields
    - Sensors
    - Docking
    - Helm/Piloting
- Any overmap console, even disconnected, will be able to view the overmap from the perspective of the ship as long as the control column has wireless toggles set to ON.
    - Separate toggles allowing wireless access, defaulting to off.
- Physical wire from control columns to a console must be present to control a ship.

### Away Destinations
- Standard map size for Main is 255x255
- Away destinations consist of procedurally generated planets ranging from 125x125 to 255x255. Loaded dynamically as needed
    - Static zlevels:
    - 3 for ship
    - 1 for centcom
    - **2** for dynamic transit at roundstart
    - 1 for lavaland
    - 1 for gateway
    - With LAA we can afford quite a lot of these
- Overmap planets will dynamically instantiate when someone attempts to land on one
    - Randomized atmosphere
    - Ruins seeded based on climate/biome
    - Perlin gen for biomes, roads, etc.

### Weapons
- Weapons are either kinetic or energy
- Energy weapons generally require power + maybe a resource to fire.
    - Basic weapons should be power only
- Kinetic weapons generally require power + ammunition
- Weapons are either hitscan or have velocity.
    - Ones with velocity will be overmaps based
    - Either click in an angle to fire them, or lock onto a ship and automatically attempt to lead the target.
    - Hitscan weapons instantly beam towards target and hitscan the first thing it collides with.
    - Most weapons should be projectile-based.
- Weapons have a falloff + maximum range
    - At falloff, damage falloff is incurred
    - At maximum, they disappear.
- Hazard tiles can't be cut through with weapons
- Hazard **objects** may be weapon-vulnerable.
    - Shoot down large meteors before they land a hit, etc
- Hits will be rounded to the closest direction, making there be an actual point to rotating a ship around.

### Shields
- We really don't want laggy bubble shields/hull shields but we'll probably need it anyways.
    - Add them anyways, for engineering to have fun with I guess.
    - They shouldn't be as strong as a ship's primary shields, but also shouldn't take that much power. Low efficiency last layer, etc.
- Ship shields will be abstract, rendered in the background of the skybox when active based on how strong they are.
- Anything attempting to enter will be blocked if there's sufficient power to block it.
- Directional strengths for front/left/right/back.
- Static shield projectors that directly consume power for shields
    - Diminishing returns on high power?
- A ship's size determines how much power is needed to maintain shields at a certain strength/recharge.
- Provides defense against meteors/weaponry up to a certain degree
    - Will **not** provide defense against docking attempts, or certain penetrative weapons.
        - Bubble/hull shields might!
- Shield diffusors for static/physical shields.
- Navigation/shields toggle to disable diffusors for hull/bubble shields, manual + automatic toggle on detecting meteors.

### Sensors
- Ships have a static sensor that detects anything within x radius. This will be weak.
- Ships have an active pulse sensor that briefly illuminates itself and anything within y radius. This will be long distance with a cooldown, and will **reveal it to other ships.**
- Sensors need to be in a full vacuum to work.
- Stealth modules can decrease "sensor receptiveness", making it required to be closer before a ship can be seen.
- A ship that gets illuminated by sensors can be scanned.
    - Weapons, armaments, mass, description, transponder.
- Ships will have transponders that are shown on sensor scans.
    - Name
    - Custom message
- Highly rare, niche only cloaking modules that fully nullify sensors and force "passive vision" only.
    - Can be flagged to have no passive vision either.

### Hazards
- Static hazards defined via flags
- /datum/overmap_entity can have a list of hazards to apply in a modular way to things crossing them until they're uncrossed
- /datum/overmap_entity will have a list of ticking hazards to apply for processing purposes, associated to a list of strengths.

### Propulsion
- Ion or electric thrusters
    - Efficiency variables
    - Electric/reactionless just takes power via a calculation
    - Ion takes power + gas via another calculation
    - Diminishing returns as input power/gas goes up for both
- Thrusters are directional.
    - UI controls: WA for forwards/backwards, AD for **turning**/rotational thrusters, QE for **left/right.**
    - Flight assist toggle. Allows for neutralizing siide motion and making WASD tank controls work instead.
    - R/F for power up/down on thrusters
    - Thrusters have a separate "volume/power" limit, used for limiting gas usage for efficiency purposes.
    - Z/X for neutralizing rotational/cardinal velocities.
- Ships have mass. This is used with thrust to calculate motion
- **Inertial dampening**
    - Thrusters usually have awful thrust in comparison with a ship's mass.
    - Inertial dampeners, another thing controlled by the core control column, can be adjusted to neutralize all or part of this mass.
    - A ship with these turned to high will be **extremely** maneuverable.
    - Ofcourse, mass is useful. When physical objects collide with you, **you want to have mass.** Having these to maximum will not be a good idea if you're being shot with kinetic weapons or pelted with meteors!
        - Amplify damage from kinetic impacts while dampeners are on, based on how much mass is left.

### Docking
- Docking will be done with docking thrusters.
    - Electric or ion
- Docking ports and their reserved areas, as well as a distance around them, can only be used if a ship has the right docking codes
    - Docking codes: randomized 8 hexadecimals without numbers.
- Without docking codes, a ship can land anywhere where there's space to (no walls or catwalks in space, or no walls on land).
- Docking will alert active sensors of an approach if they can detect the ship.
    - Sensors should radio if this happens, as well as if it was an authorized docking or "entering close proximity"
- Docking codes can be reset physically at the control column.

### FTL
- Most ships that aren't just barebones ferries will have a FTL drive.
- Powered by immense amounts of energy with specialized capacitors
- Jammed by having other, massive ships in the vicinity, as well as special gravity well/FTL jammer components.
    - Chargeup time once capacitors are charged will be decreased by this.

### AI ships
- AI ships can serve as aggressors versus player ships.
- They see the same things players do. They cannot cheat.
- Overmap backend will have vision procs. When they sensor pulse they'll see anything the sensors can see, but it'll be possible to avoid them.
- AI will use autopiloting datums to move to locations, patrol, and combat.

### UI considerations
- Each ship module can be individually controlled by a console, as long as they have a cable connection to the control column.
- Each ship "type" (datum) will have a single TGUI component showing it's direction, location etc
- There should be a console that is used for helm control, that can combine every module at once as long as it has an active wire connection to the control column.
    - Overmap/Sectormap at middle with a toggle, piloting/helm to left, aux systems via tabs to the right.

### Autopilot
- Autopilot for pathfinding to a given grid tile using JPS, avoiding certain hazards, etc.
- Autopilot for following another ship entity at a given distance
- Combat autopilot types that attempt to circle a given ship and fire at it, strafing, etc.

## Backend Implementation

- **This is the hard part. This is crucial to having this work, and doing this right means we have a reusable system we can adapt to anything from convoys on a planet to using it for some VR sim game.**
- They key to this: The backend implementation is meant to be as modular and **generic** as possible
    - Use component signals for things like checking for FTL jamming.
    - Cross/Uncross/physics are all handled by the backend. The backend does not care at all what you do with it. You can have the ships collide, you can have the ships/objects go past each other. It does not care.
    - Projectile weapons? Hook cross/uncross on the projectiles. The backend does not handle it.
- The backend consists of/handles:
    - The overmap itself
    - Sector map
    - Overmap object datums
    - A view holder that represents where someone's viewport is when they view the overmap
- Everything should use getters/setters, absolutely no snowflaking
    - Makes shifting from BYOND maps to JS/TGUI maps to potentially auxtools in the far future very easy without having to rewrite the backend

### /datum/overmap

- Holds a Cartesian plane of x by y. The edges wrap around.
- Ticks all objects within it per process. This is considered the physics/simulation tick. This happens per overmap datum.
- Every object is within a tile.
- A spatial hash of lists of objects within 10x10 squares is generated for collision/pathfinding/other purposes.
- Hazard tiles won't have their own datums, instead having a flag, like OVERMAP_TILE_METEORS | OVERMAP_TILE_CARP, etc.
    - Variable for default "strength"
    - Hazards shouldn't be hardcoded to the hazard-flag triggers. Overmap objects should also be able to trigger hazards within their borders.
    - This is the only part of the backend that isn't completely modular, for performance reasons. This can still be defined in a modular, easily overridable way, though.
- A set of icons and icon states are defined globally for hazards.

### /datum/sectormap
- Holds a Stellaris/FTL style "graph" of nodes corrosponding to overmaps
- Ships can FTL to another overmap where capable.
    - component signal for jamming
- Each node has a list of edges connecting to another.
    - One way edges/one way jumps?
    - "Distances"
    - Probably render with a JS rendering library for digraphs.
- Realistically pretty simiple, the UI is the issue.

### /datum/sector
- Icon state (either a default one in spritesheet or a custom one)
- Holds a /datum/overmap
- Holds links to other sectors, one or two directional.
- Holds distance.
- Objects will have a UID. var/static/next_uid = 1, var/uid = next_uid++
 
### /datum/overmap_object
- Represents an object in overmaps.
- Can have views attached to them.
    - When views are attached, their static vision will be read for how long the view can see.
- To avoid complexity, any overmap object can be attached to anything, anywhere from a zlevel, to a single turf reservation (which is a block of space in dynamic transit, which **is standard to how we handle shuttles**), to a single area.
    - not all objects have a physical representation
        - has_physical_instantiation(): OVERMAP_OBJECT_VIRTUAL, OVERMAP_OBJECT_INSTANTIATED, OVERMAP_OBJECT_NOT_INSTANTIATED - whether or not it can be loaded, and if it can, if it's loaded
    - Access physical areas via getters to not need to snowflake too much. Default procs should handle this well if possible.
        - get_turf_near_edge(min, max, dir)
        - get_random_turf()
        - get_center_turf()
- The only subtypes should be:
    - /datum/overmap_object/movable - Movable things
- Non movable objects will be immediately updated to all views, and sent in static data upon creation/deletion/move. Yes, you can still move these, they're just not expected to move on processing.
- Movable objects represent "hard bodies" in physics. They have a rotation and velocity.
    - Again, overmap backend is generic. It doesn't care about thrust. You only get procs from the backend to nudge/move/etc
    - All objects:
        - forceMove(x, y, datum/overmap/map)
    - Movable objects:
        - adjust_velocity(x, y)
        - turn(degrees) - clockwise
        - set_velocity(x, y) - x/y per second
        - set_rotation(degrees) - clockwise
        - set_rotation_velocity(rate) - degrees clockwise/second
- Physics/collision detection: Cross/Uncross will be **listened to** via component signals.
    - Return values may include "ALLOW_CROSS" (default), "COLLIDE_ELASTIC" (perfect rebound), "COLLIDE_INELASTIC" (stop at and equalize momentums, which will be another proc)
    - On a side note, we don't want ship crashing to be too much of a thing, so these are just there for later use if needed.
- Other events like attempting to go to another sector, etc, will also be using component signals.
- Objects will have a UID. var/static/next_uid = 1, var/uid = next_uid++

### /datum/overmap_view
- Represents a view in the overmaps.
- Contains parameters for x/y location, as well as the radius it can see
- Can either be
    - Attached to an overmaps object
    - Spawned in "detached mode", where the user can freely look around.
- Vision, only applicable in attached mode which will take these things from the object. In freelook there's no point since they can move around anyways.
    - Views have an innate vision range. They can see anything not cloaked in here.
    - Anything else will have an "alpha fade" (see overmap object, sensor support) as well as a way to override this per object. This is needed for advanced sensor support.
    - In attached mode, this is read directly from the object.
- As it moves, anything nearing its edge that hasn't updated to it yet will be updated. This is to clear up "data lag" from "lazy updates" on objects.
- Support for more expensive vision calcs for overmap AIs
- Support for creating "pulses" and other effects at locations, for things like sensor pulses.

### UI considerations
- All backend UI is handled via two components: Overmap, and SectorMap
    - The backend does not care for gameplay mechanics like thrust/piloting/sensors/etc.
- UI will have a list of flags, see view.
    - For the actual UI part, there'll be a flag somewhere along the lines of OVERMAP_VIEW_ADMIN_FULLMONTY that allows full control. Note that overmaps are datums in javascript mode, meaning admins can't physically "jump" there and MUST EDIT WITH THE UI (or VV/proccall, but most admins won't know that). An admin interface capable of arbitrarily editing, moving, instantiating, and VVing objects will be crucial for making this usable.
- The Overmap component in TGUI will require a new reducer.
    - Only send changing data.
    - Static data: send all tiles with flags for hazards.
    - Iconstates/appearances for hazards will be compiled into a spritesheet on server launch
    - When a movable object moves, it is added to an update queue. All views that can probably (we don't want expensive vision calcs here) see it will have the data updated on the next tick. When a view moves into near-range of something it will be able to see, that it does not already, it will have the data sent to it to update its position, hopefully before the player can see it.
    - Any object deletions must immediately be sent to views to avoid lingering data.
    - Object creations are counted as a "move".
- /datum/sectormap, /datum/overmap, /datum/overmap_object will all expose ui_static_data(). (for the first two) and ui_data().
- Potential reducer format:
    - Store overmaps data separately from UI data.
    - For each element in the datalist sent to the UI component:
        - ["ominit"] - Modify-Insert-Overwrite the current overmaps datalist directly. Highly inefficient, should be used only for initial static data.
        - ["sminit"] - Same but for sectormap
        - ["omreset", "smreset"] - Same but wipe all data first, used for when something switches to a different overmap/sectormap.
        - ["omtiles"] - List of lists of data to update about tiles.
        - ["omtile"] - List of data to update single tile in current overmap
        - ["omobjdel"] - List of objects by UID to delete
        - ["omobjup"] - List of objects to create or update
        - ["smobjdel"] - List of objects by UID to delete. Will automatically clear links.
        - ["smobjup"] - List of objects to create or update. Links must be populated manually!
- Icon handling
    - Static spritesheet with all default icons for performance
    - For custom adminbus icons via vv: TBD. Unsure if sending in b64 is good idea, optimally it'd inject into "omaps_spritesheet_custom" or something but also unsure if that's feasible.


## Randomness

TGen (space) and other rustg noise uses the entire seed. 32 char limit.

`03521643681958934129353213`

Planet uses the last 10 chars as base
`4129353213` which gets shifted? by the coords (x, y\[, sector?\])


