80 lines
5.1 KiB
Markdown
80 lines
5.1 KiB
Markdown
# ludic.minimap
|
|
|
|
What a map knows without drawing anything: which cells of a grid have been walked, the marks the
|
|
player put on it, and where its window looks. The game paints the picture - the ground, the fog,
|
|
the icons, the legend - from the package's queries. Uses [`ludic.base`](../ludic.base/README.md)
|
|
and nothing else.
|
|
|
|
```ludic
|
|
import "ludic.minimap"
|
|
```
|
|
|
|
## The explored fog
|
|
|
|
A square grid of `cells` per side, `cell_m` metres each, centred on `MinimapWorld.origin`.
|
|
`minimap_reveal(x, z, r)` marks every cell any part of which lies within `r`; `minimap_version()`
|
|
goes up whenever what has been seen changes, so a baked fog texture is rebuilt only then.
|
|
**Explored** is a share of LAND, over a core square of the grid (`minimap_config_core`), so open
|
|
water is not unexplored and a bigger grid does not change what a chapter's "walk 30%" asks for.
|
|
|
|
## The marks
|
|
|
|
A mark (`MinimapPin { x, z, icon, colour, day, label }`) is a note at a place: it does not route
|
|
anyone and it does not move. There is a cap; `minimap_pin_add` answers -1 past it and the game
|
|
says so. One mark may be **open** (the legend edits it) and one **followed** (the game puts it on
|
|
its compass); a new mark takes the symbol last chosen. Rubbing one out moves the later ones up,
|
|
and the open and followed indices with them.
|
|
|
|
## The view
|
|
|
|
A square window of `size` pixels showing `span` metres across at zoom 1, centred on a world point
|
|
and kept inside `MinimapWorld`'s bounds. World to window (`minimap_px`, `minimap_py`) and back
|
|
(`minimap_wx`, `minimap_wz`, from a point measured from the window's corner), zoom in steps or
|
|
about a point (what is under the pointer stays under it), a drag that pans, a press that picks the
|
|
mark under it or drops a new one, "the camp" and "you", and a focus that goes there and closes in
|
|
but never pulls a closer view back out.
|
|
|
|
## The port
|
|
|
|
```ludic
|
|
export port MinimapWorld { # every member has a default
|
|
origin_x, origin_z # the grid's centre
|
|
land(x, z) -> bool # what "explored" counts
|
|
you_x, you_z, camp_x, camp_z # the two places a view recentres on
|
|
day() -> int # a mark remembers the day it was made
|
|
lo_x, lo_z, hi_x, hi_z # the view's centre stays inside these
|
|
}
|
|
```
|
|
|
|
## API
|
|
|
|
| | |
|
|
| --- | --- |
|
|
| `minimap_config(cells, cell_m)`, `minimap_config_core(from, n)`, `minimap_land_changed()` | the grid, the square explored is measured over, and a new ground under it |
|
|
| `minimap_reveal(x, z, r)`, `minimap_reveal_cell(c)` | walking |
|
|
| `minimap_cell(x, z)`, `minimap_cells()`, `minimap_cell_m()`, `minimap_cell_x(i)`, `minimap_cell_z(j)`, `minimap_grid_x0()`, `minimap_grid_z0()`, `minimap_grid_half()` | the grid's geometry |
|
|
| `minimap_seen(c)`, `minimap_seen_at(x, z)`, `minimap_seen_count()`, `minimap_version()`, `minimap_explored_pct()` | what has been seen |
|
|
| `minimap_seen_text()`, `minimap_seen_from_text(s)` | the grid as one string of 0 / 1 (an older save's shape) |
|
|
| `minimap_config_pins(max, symbols, colours)`, `minimap_pins_clear()` | the marks' cap and ranges |
|
|
| `minimap_pin_add(x, z, icon, label) -> int`, `minimap_pin_put(x, z, icon, colour, day, label)`, `minimap_pin_remove(i)` | a mark made today, one as saved, and rubbing one out |
|
|
| `minimap_pin_count()`, `minimap_pin_max()`, `minimap_pin_full()`, `minimap_pin(i) -> MinimapPin` | the marks |
|
|
| `minimap_pin_set_label/icon/colour(i, v)`, `minimap_pin_last_icon()` | editing one |
|
|
| `minimap_pin_open()`, `minimap_pin_select(i)`, `minimap_pin_followed()`, `minimap_pin_follow(i)`, `minimap_pin_follow_toggle()` | the open one and the followed one |
|
|
| `minimap_pins_near(x, z, n, within) -> []int` | the nearest marks, not the followed one (for a compass), in a list the state keeps and refills: read it, do not keep it |
|
|
| `minimap_config_view(span, zoom_min, zoom_max, focus)`, `minimap_window(x0, y0, size)` | the view's range, and where the window is this frame |
|
|
| `minimap_px(x)`, `minimap_py(z)`, `minimap_wx(rx)`, `minimap_wz(ry)`, `minimap_span()`, `minimap_scale()`, `minimap_scale_metres()` | projection, and a scale bar's round distance |
|
|
| `minimap_zoom()`, `minimap_zoom_set(z)`, `minimap_zoom_step(dir)`, `minimap_zoom_about(rx, ry, factor)` | zoom |
|
|
| `minimap_view_x()`, `minimap_view_z()`, `minimap_have_view()`, `minimap_centre(x, z)`, `minimap_clamp()`, `minimap_recentre(on_you)`, `minimap_focus(on_you)` | where it looks |
|
|
| `minimap_pan_begin(rx, ry)`, `minimap_pan_to(rx, ry)`, `minimap_pan_end()`, `minimap_panning()` | a drag |
|
|
| `minimap_pick(rx, ry, r) -> int`, `minimap_placing()`, `minimap_place_toggle()`, `minimap_place(rx, ry, label) -> int` | a press: open the mark under it, or drop the next one there |
|
|
| `minimap_reset()`, `minimap_system() -> System` | `"minimap"`: the seen grid, the marks, the followed one and the last symbol in its own section, by key; the view is not saved |
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
ludic test packages/ludic.minimap
|
|
```
|
|
|
|
A 20 x 20 grid with sea on one side: the cells, revealing and the land's share, the marks' cap,
|
|
editing and rubbing out, the nearest for a compass, projection, zoom about a point, a pan, focus
|
|
and the clamp, picking and placing, the scale bar, and the save.
|