Struct twmap::TwMap

pub struct TwMap {
    pub version: Version,
    pub info: Info,
    pub images: Vec<Image>,
    pub envelopes: Vec<Envelope>,
    pub groups: Vec<Group>,
    pub sounds: Vec<Sound>,
}

The TwMap struct represents a Teeworlds 0.7 map or a DDNet 0.6 map. Which one of those it is will always be determined during the parsing process and is stored in the version field.

The library cares a lot about the integrity of the struct. The check method verifies that all limitations are met.

Parsing

TwMap has several different parsing methods: parse, parse_path, parse_file, parse_dir, parse_datafile

Each of them execute the check method to finalize the process.

If you want to leave out the checks, you can use the _unchecked variation of that parsing method if it is provided. Note that the _unchecked variation might also exclude some common fixes.

Saving

TwMap can save maps in the binary format (save, save_file) and in the MapDir format (save_dir).

Each saving method will first execute check, if the map fails the check, it will not be saved.

Loading

When loading a map from the binary format, a lot of data will be decompressed in the process. Since this is the main slowdown factor, some larger data chunks will be left compressed. The compressed parts are the data field in Images and Sounds and the tiles field in tilemap layers. If you want to save the map at the end anyways, then you can simply use the load method on the entire map. If not, use the load method only on the images, sounds and tilemap layers that you want to use.

Note:

• you can also use load on slices and vectors of Images, Sounds, Layers, Groups with layers,
• some methods rely on having parts of the map loaded, especially more abstract methods like mirror and rotate_right
• if you want to leave out the checks on the decompressed data, you can use the load_unchecked methods

Fixed Point Integers

In many parts of the struct fixed point integers are used. They are represented using the crate fixed. Position and size fixed point integers are always chosen so that 1 always translates to the width of 1 tile. The other usages are usually chosen so that 0 = 0%, 1 = 100%.

Fields

version: Version

Determines what version this map should be saved as

info: Info

Metadata

images: Vec<Image>

Textures

envelopes: Vec<Envelope>

Animation strips

groups: Vec<Group>

Collections of layers

sounds: Vec<Sound>

Sfx (not available in Teeworlds07 maps)

Implementations

impl TwMap

pub fn check(&self) -> Result<(), MapError>

impl TwMap

pub fn extend_layers( self, up_left: Extent2<u16>, down_right: Extent2<u16> ) -> Option<TwMap>

Increases the size of the tilemap layers by the specified tile amount in each direction. To keep the look of the map the same, this also moves the quads in quads layers and adjust the offset of groups as well as their clipping. Returns None if an overflow occurred.

impl TwMap

pub fn mirror(self) -> Option<TwMap>

Mirrors the map. Switches left and right. Returns None if an overflow occurred.

impl TwMap

pub fn rotate_right(self) -> Option<TwMap>

Rotates the map clockwise. Returns None if an overflow occurred.

impl TwMap

pub fn scale(self, factor: u8) -> Option<Self>

Panics:

• The factor must be one of 2, 4, 8 or 16!
• All images must be embedded

impl TwMap

pub fn lossless_shrink_layers(self) -> Option<TwMap>

Downsizes all tilemap layers as much as possible. Note that this will also reduce the size of physics layers and thereby moves the world border! Downsizing is possible as long as any outer edge is the same as the it’s neighboring row/column. Because of this, it is suggested to use TwMap::edit_tiles with ZeroAir before using this method.

Returns None if an overflow occurred.

pub fn lossless_shrink_tiles_layers(self) -> Option<TwMap>

Downsizes all tiles layers as much as possible. Downsizing is possible as long as any outer edge is the same as the it’s neighboring row/column. Because of this, it is suggested to use TwMap::edit_tiles with ZeroAir before using this method. Returns None if an overflow occurred.

impl TwMap

pub fn remove_duplicate_physics_layers(&mut self) -> u16

Removes duplicate physics layers of each type. Note that every map must have at most 1 physics layer of each type to pass the checks. The removal process prioritizes removing the layers in front.

impl TwMap

pub fn remove_everything_unused(&mut self) -> u32

Combination of every other remove_unused method.

pub fn remove_unused_layers(&mut self) -> u16

Removes all layers for which is_empty returns true.

pub fn remove_unused_groups(&mut self) -> u16

Removes all groups that contain zero layers.

pub fn is_image_in_use(&self, index: u16) -> bool

Returns true if the image index is set for a tiles layer or a quad.

pub fn remove_unused_images(&mut self) -> (u16, u16)

Removes all images for which is_image_in_use returns false. Return value: (count of removed external images, count of removed embedded images)

pub fn is_sound_in_use(&self, index: u16) -> bool

Returns true if the sound index is set for a sounds layer.

pub fn remove_unused_sounds(&mut self) -> u16

Removes all sounds for which is_sound_in_use returns false.

pub fn is_env_in_use(&self, index: u16) -> bool

Returns true if the envelope index is in use.

pub fn remove_unused_envelopes(&mut self) -> u16

Removes all sounds for which is_env_in_use returns false.

impl TwMap

pub fn find_physics_layer<T: PhysicsLayer>(&self) -> Option<&T>

Returns a reference to the specified physics layer, if the map contains it. Note that every map must have a Game layer to pass the checks.

pub fn find_physics_layer_mut<T: PhysicsLayer>(&mut self) -> Option<&mut T>

Returns a mutable reference to the specified physics layer, if the map contains it. Note that every map must have a Game layer to pass the checks.

impl TwMap

pub fn parse_path_unchecked<P: AsRef<Path>>(path: P) -> Result<Self, Error>

pub fn parse_path<P: AsRef<Path>>(path: P) -> Result<Self, Error>

Parses binary as well as MapDir maps.

impl TwMap

pub fn embed_images<P: AsRef<Path>>( &mut self, mapres_directory: P ) -> Result<(), ImageError>

Tries to embed the external images by loading them from the file <mapres_directory>/<image_name>

pub fn embed_images_auto(&mut self) -> Result<(), ImageError>

Embed images with the twstorage file paths. This will take the config directory into account.

impl TwMap

pub fn edit_image_indices( &mut self, edit_fn: impl Fn(Option<u16>) -> Option<u16> )

For easy remapping of all image indices in tiles layers and quads.

pub fn edit_env_indices(&mut self, edit_fn: impl Fn(Option<u16>) -> Option<u16>)

For easy remapping of all envelope indices in tiles, quads and sounds layers.

pub fn edit_sound_indices( &mut self, edit_fn: impl Fn(Option<u16>) -> Option<u16> )

For easy remapping of all sound indices in sounds layers.

impl TwMap

pub fn process_tile_flag_opaque(&mut self)

Fill in all OPAQUE tile flags.

pub fn set_external_image_dimensions(&mut self)

Set the width and height of external images to their default values.

impl TwMap

pub fn edit_tiles<T: EditTile>(&mut self)

Requires the tiles to be loaded

impl TwMap

pub fn isolate_physics_layers(&mut self)

Move cosmetic layers from the physics group into separate groups, keeping the render order

impl TwMap

pub fn empty(version: Version) -> TwMap

Returns a empty map struct with only the version set.

pub fn physics_group(&self) -> &Group

Returns a reference to the physics group.

pub fn physics_group_mut(&mut self) -> &mut Group

Returns a mutable reference to the physics group.

impl TwMap

pub fn load(&mut self) -> Result<(), MapError>

pub fn load_unchecked(&mut self) -> Result<(), MapError>

impl TwMap

pub fn save_dir<P: AsRef<Path>>(&mut self, path: P) -> Result<(), Error>

Saves the map in the MapDir format to the passed path. Will not overwrite existing files/directories, this would result in an IO-error.

pub fn parse_dir<P: AsRef<Path>>(path: P) -> Result<TwMap, Error>

For parsing a TwMap map directory.

pub fn parse_dir_unchecked<P: AsRef<Path>>(path: P) -> Result<TwMap, Error>

impl TwMap

pub fn parse_file<P: AsRef<Path>>(path: P) -> Result<TwMap, Error>

For parsing a binary map file.

pub fn parse_file_unchecked<P: AsRef<Path>>(path: P) -> Result<TwMap, Error>

pub fn parse(data: &[u8]) -> Result<TwMap, Error>

For parsing binary map data.

pub fn parse_unchecked(data: &[u8]) -> Result<TwMap, Error>

pub fn parse_datafile(df: &Datafile<'_>) -> Result<TwMap, Error>

Parses the TwMap struct from a Datafile. Afterwards, it runs TwMap::check.

pub fn parse_datafile_unchecked( df: &Datafile<'_> ) -> Result<TwMap, MapParseError>

Parses the TwMap struct from a Datafile. This function explicitly doesn’t run TwMap::check after parsing.

impl TwMap

pub fn save_file<P: AsRef<Path>>(&mut self, path: P) -> Result<(), Error>

Saves the map in the binary format. Will overwrite if that file already exists.

pub fn save(&mut self, output: &mut dyn Write) -> Result<(), Error>

Saves the map in the binary format. Since it uses a dyn Write as a parameter, you are free to save it into a vec, file, etc.

Trait Implementations

impl Clone for TwMap

fn clone(&self) -> TwMap

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TwMap

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for TwMap

fn eq(&self, other: &TwMap) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for TwMap

impl StructuralPartialEq for TwMap