nwnrs-set 0.0.8

Typed Neverwinter Nights tileset SET parser
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

# nwnrs-set

Typed parser for Neverwinter Nights tileset (`SET`) payloads.

## Scope

- parse the INI-like tileset structure into typed sections
- build deterministic `SET` text from the typed representation
- write typed tilesets back to a stream
- model tiles, terrain tags, crosser tags, groups, grass settings, and tile
  door metadata explicitly
- expose the authored tileset catalog without coupling it to a renderer

The primary entry points are [`read_set`], [`build_set_text`], [`write_set`],
and [`SetFile`].

## Public Surface

- `SET_RES_TYPE`
- `SetError`
- `SetResult`
- `SetFile`
- `SetGeneral`
- `SetGrass`
- `SetNamedType`
- `SetPrimaryRule`
- `SetTile`
- `SetTileCorner`
- `SetTileEdges`
- `SetTileDoor`
- `SetGroup`
- `read_set`
- `parse_set`
- `build_set_text`
- `write_set`

## Core Model

`SetFile` preserves distinct keyed collections for:

- `general`
- optional `grass`
- `terrains`
- `crossers`
- `primary_rules`
- `tiles`
- `tile_doors`
- `groups`

Important typed pieces:

- `SetTileCorner`
  - terrain tag
  - height step
- `SetTileEdges`
  - explicit top, right, bottom, and left crosser tags
- `SetTile`
  - model reference
  - walkmesh reference
  - terrain annotations
  - lighting and animation flags
  - tile-level visibility and pathing metadata

## Text Layout

`SET` is INI-like and section-oriented.

```text
[GENERAL]
...

[GRASS]
...

[TERRAIN0]
...

[CROSSER0]
...

[PRIMARY RULE0]
...

[TILE0]
...

[TILE0DOOR0]
...

[GROUP0]
...
```

Conceptually:

```text
+----------------------+
| global metadata      |
+----------------------+
| optional grass block |
+----------------------+
| terrain catalog      |
+----------------------+
| crosser catalog      |
+----------------------+
| rule catalog         |
+----------------------+
| tile catalog         |
+----------------------+
| tile-door metadata   |
+----------------------+
| groups               |
+----------------------+
```

## Invariants

- section identity is preserved explicitly through typed collections keyed by
  their authored ids
- tile, group, terrain, crosser, and door metadata remain distinct rather than
  being merged into one generic map
- optional values remain optional rather than being normalized to arbitrary
  defaults
- deterministic serialization rebuilds the modeled section structure in
  ascending key order

## See also

- [`nwnrs-git`](https://docs.rs/nwnrs-git), which models the area instance data
  that references tileset resources
- [`nwnrs-mdl`](https://docs.rs/nwnrs-mdl), which handles the model assets that
  tileset tile entries point to

## Why This Crate Exists

`SET` is one of the clearest examples in the workspace of "catalog structure is
data." If you flatten it into one generic section map, you lose too much:

- explicit typed tile semantics
- tile-door relationship structure
- terrain and crosser taxonomy
- deterministic reconstruction of the authored tileset catalog