Add crate-level documentation, examples

src/lib.rs

@@ -1,3 +1,62 @@
+//! # Tools for reading/writing ZZT's file formats
+//!
+//! zztff is a library for working with [ZZT](https://en.wikipedia.org/wiki/ZZT) world and board files.
+//! It is somewhat low-level; it allows control over every data field used by ZZT,
+//! but creating new files requires some familiarity with the file format.
+//!
+//! zztff currently only supports the format used by ZZT 3.2, the last official release.
+//! Super ZZT (the sequel) is not currently supported.
+//!
+//! ## Examples
+//!
+//! ### Reading an existing .ZZT file
+//!
+//! ```rust,no_run
+//! let bytes = std::fs::read("TOWN.ZZT")?;
+//! let world = zztff::World::from_bytes(&bytes)?;
+//! let first3: Vec<&str> = world.boards.iter().take(3).map(|b| b.name.as_str()).collect();
+//! println!("Loaded world {:?}, {} boards.", world.name, world.boards.len());
+//! println!("First 3 boards: {:?}", first3);
+//! # Ok::<(), Box<dyn std::error::Error>>(())
+//! ```
+//!
+//! Assuming you have TOWN.ZZT, this loads the file and prints a brief summary:
+//!
+//! ```text
+//! Loaded world "TOWN", 34 boards.
+//! First 3 boards: ["Introduction Screen", "Room One", "Armory"]
+//! ```
+//!
+//! ### Creating a new .ZZT file
+//!
+//! Creating a valid world file from scratch is more involved.
+//! Worlds must contain at least one board, and we must populate that board with a player.
+//! And to create a functioning player, we must create a corresponding stat to allow the player tile to move around.
+//!
+//! ```rust,no_run
+//! use zztff::{World, Board, Tile, Stat, Element};
+//!
+//! let mut world = World::default();
+//! world.name = "HELLO".into();    // should match stem of filename
+//!
+//! let mut board = Board::default();
+//! board.set_tile(30, 12, Tile {   // place a player tile in the center, at (30, 12)
+//!     element: Element::Player as u8,
+//!     color: 0x1f,
+//! });
+//! board.stats.push(Stat {
+//!     x: 30,                      // associate a stat with the player tile at (30, 12)
+//!     y: 12,
+//!     cycle: 1,
+//!     ..Stat::default()
+//! });
+//! world.boards.push(board);
+//!
+//! let bytes = world.to_bytes()?;
+//! std::fs::write("HELLO.ZZT", &bytes)?;
+//! # Ok::<(), Box<dyn std::error::Error>>(())
+//! ```
+
 mod elements;
 mod errors;
 mod text;