rakata_generics/
lib.rs

1//! Typed views over the game's blueprint and template resources.
2//!
3//! KotOR stores most of its non-asset content in [GFF](rakata_formats::Gff),
4//! a generic labelled-tree container. The files in this crate are the formats
5//! built on it: creatures, doors, items, placeables, triggers, waypoints,
6//! sounds, merchants, areas, dialogue, factions and module info. A typed view
7//! reads one of those trees and presents its contents as named Rust fields, so
8//! a caller works with `creature.hp` rather than looking up the label
9//! `HitPoints` and unwrapping a `GffValue`.
10//!
11//! ## A typed view is a projection, not a copy
12//!
13//! **A typed view models a field only where the engine reads it at that path.**
14//! Fields the engine never looks at are deliberately absent, even when vanilla
15//! files carry them. The consequence is the thing to know before choosing
16//! between this crate and the raw container:
17//!
18//! **`from_gff` followed by `to_gff` does not round-trip byte for byte.**
19//! Anything the view does not model is dropped, because the view has nowhere
20//! to keep it. Carrying unmodelled data along silently would make the view a
21//! worse answer to the question it exists for.
22//!
23//! So pick by what the job needs. **Reading or editing engine-meaningful
24//! fields**, which is validation, inspection and most editing, is what these
25//! types are for. **Preserving a file exactly**, which is byte-faithful
26//! round-tripping and diffing against an original, means holding the
27//! [`Gff`](rakata_formats::Gff) tree and editing that.
28//!
29//! ## `author_`, not `write_`
30//!
31//! Every other format in the tree pairs `read_x_from_bytes` with
32//! `write_x_to_vec`, and that pair reads as a promise: what came out goes back
33//! in. These functions cannot keep it, for the reason above. So they are
34//! spelled `author_` and the shape is otherwise unchanged, `<W: Write>` sibling
35//! included.
36//!
37//! ## Clone discipline in `to_gff()` methods
38//!
39//! Serialization methods take `&self` and hand owned data to `GffValue`
40//! variants, which store an owned `String`, `GffLocalizedString` or `Vec<_>`.
41//! `&self` cannot move fields out, so the clone is unavoidable. Uniform across
42//! every typed view here, and not flagged per-clone.
43
44#![forbid(unsafe_code)]
45#![warn(clippy::as_conversions)]
46#![deny(missing_docs)]
47#![deny(clippy::missing_errors_doc)]
48
49/// Typed ARE (`.are`) area environment and conversion helpers.
50pub mod are;
51/// Typed DLG (`.dlg`) dialogue tree and conversion helpers.
52pub mod dlg;
53/// Typed FAC (`.fac`) faction table and conversion helpers.
54pub mod fac;
55mod from_gff;
56/// Typed GIT (`.git`) area instance layout and conversion helpers.
57pub mod git;
58/// Typed IFO (`.ifo`) module info and conversion helpers.
59pub mod ifo;
60/// Shared typed components reused across generic wrappers.
61pub mod shared;
62/// Typed UTC (`.utc`) creature blueprint and conversion helpers.
63pub mod utc;
64/// Typed UTD (`.utd`) door blueprint and conversion helpers.
65pub mod utd;
66/// Typed UTE (`.ute`) encounter blueprint and conversion helpers.
67pub mod ute;
68/// Typed UTI (`.uti`) item blueprint and conversion helpers.
69pub mod uti;
70/// Typed UTM (`.utm`) merchant blueprint and conversion helpers.
71pub mod utm;
72/// Typed UTP (`.utp`) placeable blueprint and conversion helpers.
73pub mod utp;
74/// Typed UTS (`.uts`) sound emitter blueprint and conversion helpers.
75pub mod uts;
76/// Typed UTT (`.utt`) trigger blueprint and conversion helpers.
77pub mod utt;
78/// Typed UTW (`.utw`) waypoint blueprint and conversion helpers.
79pub mod utw;
80
81/// Authors the ARE file the typed view describes, into a writer.
82pub use are::author_are;
83/// Authors the ARE file the typed view describes, as bytes.
84pub use are::author_are_to_vec;
85/// Reads typed ARE data from a reader.
86pub use are::read_are;
87/// Reads typed ARE data from bytes.
88pub use are::read_are_from_bytes;
89/// Typed ARE model.
90pub use are::Are;
91/// Errors produced while reading/writing typed ARE data.
92pub use are::AreError;
93pub use are::AreMap;
94/// Typed mini-game model for ARE resources.
95pub use are::AreMiniGame;
96/// Ballistics of one mini-game gun bank.
97pub use are::AreMiniGameBullet;
98/// Typed mini-game enemy model for ARE resources.
99pub use are::AreMiniGameEnemy;
100/// One weapon hardpoint on a mini-game vehicle.
101pub use are::AreMiniGameGunBank;
102/// Typed mini-game model entry for ARE resources.
103pub use are::AreMiniGameModel;
104/// Typed mini-game mouse settings for ARE resources.
105pub use are::AreMiniGameMouse;
106/// Base script slots shared by every mini-game object.
107pub use are::AreMiniGameObjectScripts;
108/// Typed mini-game obstacle model for ARE resources.
109pub use are::AreMiniGameObstacle;
110/// Typed mini-game player model for ARE resources.
111pub use are::AreMiniGamePlayer;
112/// Engine and destruction sounds on a mini-game vehicle.
113pub use are::AreMiniGameSounds;
114/// AI aiming parameters on an enemy gun bank.
115pub use are::AreMiniGameTargeting;
116/// Fields shared by the mini-game player and every enemy.
117pub use are::AreMiniGameVehicle;
118/// Script slots a mini-game vehicle adds over the base set.
119pub use are::AreMiniGameVehicleScripts;
120/// Typed nested room model for ARE resources.
121pub use are::AreRoom;
122/// The `BankID` value meaning the engine skips a gun bank.
123pub use are::BANK_ID_NONE;
124/// Authors the DLG file the typed view describes, into a writer.
125pub use dlg::author_dlg;
126/// Authors the DLG file the typed view describes, as bytes.
127pub use dlg::author_dlg_to_vec;
128/// Reads typed DLG data from a reader.
129pub use dlg::read_dlg;
130/// Reads typed DLG data from bytes.
131pub use dlg::read_dlg_from_bytes;
132/// Typed DLG model.
133pub use dlg::Dlg;
134/// Typed DLG animation entry model.
135pub use dlg::DlgAnimation;
136/// Errors produced while reading/writing typed DLG data.
137pub use dlg::DlgError;
138/// Typed DLG link model.
139pub use dlg::DlgLink;
140/// Typed DLG dialogue node model.
141pub use dlg::DlgNode;
142/// Typed DLG cutscene stunt model.
143pub use dlg::DlgStunt;
144/// Authors the FAC file the typed view describes, into a writer.
145pub use fac::author_fac;
146/// Authors the FAC file the typed view describes, as bytes.
147pub use fac::author_fac_to_vec;
148/// Reads typed FAC data from a reader.
149pub use fac::read_fac;
150/// Reads typed FAC data from bytes.
151pub use fac::read_fac_from_bytes;
152/// Typed FAC faction-table model.
153pub use fac::Fac;
154/// Errors produced while reading/writing typed FAC data.
155pub use fac::FacError;
156/// One faction from a FAC `FactionList`.
157pub use fac::FacFaction;
158/// Reaction band a faction standing falls into.
159pub use fac::FacReaction;
160/// One stored standing from a FAC `RepList`.
161pub use fac::FacReputation;
162/// The schema of the view modelling a container, found by its magic.
163pub use from_gff::schema_for;
164/// Authors the GIT file the typed view describes, into a writer.
165pub use git::author_git;
166/// Authors the GIT file the typed view describes, as bytes.
167pub use git::author_git_to_vec;
168/// Shared lock state for doors and placeables.
169pub use git::blocks::LockState;
170/// Shared position and facing block for door and placeable placements.
171pub use git::blocks::Placement;
172/// Shared saving throws for doors and placeables.
173pub use git::blocks::SavingThrows;
174/// How a saved object names its portrait.
175pub use git::blocks::{DoorPortraitLabels, SavedPortrait, SavedPortraitLabels};
176/// One class entry from a saved creature's ClassList.
177pub use git::creature::SavedClass;
178/// A creature as stored inside a save game's module GIT.
179pub use git::creature::SavedCreature;
180/// A door as stored inside a save game's module GIT.
181pub use git::door::SavedDoor;
182/// One item as stored in a save.
183pub use git::item::SavedItem;
184/// A placeable as stored inside a save game's module GIT.
185pub use git::placeable::SavedPlaceable;
186/// Reads typed GIT data from a reader.
187pub use git::read_git;
188/// Reads typed GIT data from bytes.
189pub use git::read_git_from_bytes;
190/// A sound emitter as stored inside a save game's module GIT.
191pub use git::sound::SavedSound;
192/// A merchant store as stored inside a save game's module GIT.
193pub use git::store::SavedStore;
194/// A trigger as stored inside a save game's module GIT.
195pub use git::trigger::SavedTrigger;
196/// Typed GIT model.
197pub use git::Git;
198/// Typed GIT area-of-effect instance model.
199pub use git::GitAreaEffect;
200/// The dimensions an area-of-effect object covers.
201pub use git::GitAreaEffectShape;
202/// Typed GIT area properties model.
203pub use git::GitAreaProperties;
204/// Typed GIT camera model.
205pub use git::GitCamera;
206/// Typed GIT creature instance model.
207pub use git::GitCreature;
208/// The two forms a GIT `Creature List` can take.
209pub use git::GitCreatures;
210/// Typed GIT door instance model.
211pub use git::GitDoor;
212/// Typed GIT encounter instance model.
213pub use git::GitEncounter;
214/// Typed GIT encounter geometry point model.
215pub use git::GitEncounterPoint;
216/// Errors produced while reading/writing typed GIT data.
217pub use git::GitError;
218/// Typed GIT item instance model.
219pub use git::GitItem;
220/// A waypoint map note.
221pub use git::GitMapNote;
222/// The two forms any GIT object list can take.
223pub use git::GitObjects;
224/// Typed GIT placeable instance model.
225pub use git::GitPlaceable;
226/// Typed GIT sound instance model.
227pub use git::GitSound;
228/// Typed GIT spawn point model.
229pub use git::GitSpawnPoint;
230/// Typed GIT store instance model.
231pub use git::GitStore;
232/// Typed GIT trigger instance model.
233pub use git::GitTrigger;
234/// Typed GIT waypoint instance model.
235pub use git::GitWaypoint;
236/// Authors the IFO file the typed view describes, into a writer.
237pub use ifo::author_ifo;
238/// Authors the IFO file the typed view describes, as bytes.
239pub use ifo::author_ifo_to_vec;
240/// Reads typed IFO data from a reader.
241pub use ifo::read_ifo;
242/// Reads typed IFO data from bytes.
243pub use ifo::read_ifo_from_bytes;
244/// Typed IFO model.
245pub use ifo::Ifo;
246/// Typed IFO area list entry model.
247pub use ifo::IfoArea;
248/// Typed IFO cutscene list entry model.
249pub use ifo::IfoCutScene;
250/// Errors produced while reading/writing typed IFO data.
251pub use ifo::IfoError;
252/// Typed IFO expansion list entry model.
253pub use ifo::IfoExpansion;
254/// Typed IFO player list entry model.
255pub use ifo::IfoPlayer;
256/// Typed IFO token entry model.
257pub use ifo::IfoToken;
258/// A runtime object handle, defaulting to the engine's invalid placeholder.
259pub use shared::ObjectId;
260/// Authors the UTC file the typed view describes, into a writer.
261pub use utc::author_utc;
262/// Authors the UTC file the typed view describes, as bytes.
263pub use utc::author_utc_to_vec;
264/// Reads typed UTC data from a reader.
265pub use utc::read_utc;
266/// Reads typed UTC data from bytes.
267pub use utc::read_utc_from_bytes;
268/// Typed UTC model.
269pub use utc::Utc;
270/// Typed UTC class entry model.
271pub use utc::UtcClass;
272/// Errors produced while reading/writing typed UTC data.
273pub use utc::UtcError;
274/// Typed UTC skill set model.
275pub use utc::UtcSkills;
276/// Authors the UTD file the typed view describes, into a writer.
277pub use utd::author_utd;
278/// Authors the UTD file the typed view describes, as bytes.
279pub use utd::author_utd_to_vec;
280/// Reads typed UTD data from a reader.
281pub use utd::read_utd;
282/// Reads typed UTD data from bytes.
283pub use utd::read_utd_from_bytes;
284/// Typed UTD model.
285pub use utd::Utd;
286/// Errors produced while reading/writing typed UTD data.
287pub use utd::UtdError;
288/// Authors the UTE file the typed view describes, into a writer.
289pub use ute::author_ute;
290/// Authors the UTE file the typed view describes, as bytes.
291pub use ute::author_ute_to_vec;
292/// Reads typed UTE data from a reader.
293pub use ute::read_ute;
294/// Reads typed UTE data from bytes.
295pub use ute::read_ute_from_bytes;
296/// Typed UTE model.
297pub use ute::Ute;
298/// Typed UTE area list entry model.
299pub use ute::UteAreaEntry;
300/// Typed UTE creature entry model.
301pub use ute::UteCreature;
302/// Errors produced while reading/writing typed UTE data.
303pub use ute::UteError;
304/// Typed UTE geometry vertex model.
305pub use ute::UteGeometryVertex;
306/// Typed UTE spawn entry model.
307pub use ute::UteSpawnEntry;
308/// Typed UTE spawn point model.
309pub use ute::UteSpawnPoint;
310/// Authors the UTI file the typed view describes, into a writer.
311pub use uti::author_uti;
312/// Authors the UTI file the typed view describes, as bytes.
313pub use uti::author_uti_to_vec;
314/// Reads typed UTI data from a reader.
315pub use uti::read_uti;
316/// Reads typed UTI data from bytes.
317pub use uti::read_uti_from_bytes;
318/// Typed UTI model.
319pub use uti::Uti;
320/// Errors produced while reading/writing typed UTI data.
321pub use uti::UtiError;
322/// Typed UTI property entry model.
323pub use uti::UtiProperty;
324/// Authors the UTM file the typed view describes, into a writer.
325pub use utm::author_utm;
326/// Authors the UTM file the typed view describes, as bytes.
327pub use utm::author_utm_to_vec;
328/// Reads typed UTM data from a reader.
329pub use utm::read_utm;
330/// Reads typed UTM data from bytes.
331pub use utm::read_utm_from_bytes;
332/// Typed UTM model.
333pub use utm::Utm;
334/// Errors produced while reading/writing typed UTM data.
335pub use utm::UtmError;
336/// Typed UTM inventory entry model.
337pub use utm::UtmInventoryItem;
338/// Authors the UTP file the typed view describes, into a writer.
339pub use utp::author_utp;
340/// Authors the UTP file the typed view describes, as bytes.
341pub use utp::author_utp_to_vec;
342/// Reads typed UTP data from a reader.
343pub use utp::read_utp;
344/// Reads typed UTP data from bytes.
345pub use utp::read_utp_from_bytes;
346/// Typed UTP model.
347pub use utp::Utp;
348/// Errors produced while reading/writing typed UTP data.
349pub use utp::UtpError;
350/// Typed UTP inventory entry model.
351pub use utp::UtpInventoryItem;
352/// Authors the UTS file the typed view describes, into a writer.
353pub use uts::author_uts;
354/// Authors the UTS file the typed view describes, as bytes.
355pub use uts::author_uts_to_vec;
356/// Reads typed UTS data from a reader.
357pub use uts::read_uts;
358/// Reads typed UTS data from bytes.
359pub use uts::read_uts_from_bytes;
360/// Typed UTS model.
361pub use uts::Uts;
362/// Errors produced while reading/writing typed UTS data.
363pub use uts::UtsError;
364/// Typed UTS sound entry model.
365pub use uts::UtsSound;
366/// Authors the UTT file the typed view describes, into a writer.
367pub use utt::author_utt;
368/// Authors the UTT file the typed view describes, as bytes.
369pub use utt::author_utt_to_vec;
370/// Reads typed UTT data from a reader.
371pub use utt::read_utt;
372/// Reads typed UTT data from bytes.
373pub use utt::read_utt_from_bytes;
374/// Typed UTT model.
375pub use utt::Utt;
376/// Errors produced while reading/writing typed UTT data.
377pub use utt::UttError;
378/// Authors the UTW file the typed view describes, into a writer.
379pub use utw::author_utw;
380/// Authors the UTW file the typed view describes, as bytes.
381pub use utw::author_utw_to_vec;
382/// Reads typed UTW data from a reader.
383pub use utw::read_utw;
384/// Reads typed UTW data from bytes.
385pub use utw::read_utw_from_bytes;
386/// Typed UTW model.
387pub use utw::Utw;
388/// Errors produced while reading/writing typed UTW data.
389pub use utw::UtwError;
rakata_generics/lib.rs

rakata_generics/
lib.rs
