Jazz2::Editor::LevelDocument class

A level being edited.

Holds everything a level file stores, nothing is lost by loading a level and saving it again — the file comes out byte for byte the same. It knows nothing of the engine, a level is played from the file it writes. Changes that should be undoable go through edit commands (see CommandHistory), which tell what they changed by a DocumentChange.

Tiles are referred to by TileRef, so adding a tile set or an animation doesn't touch any layer. Most tiles of the event grid are empty, only those with something in them are stored.

Data that only the editor uses — which layers are hidden, the editor's own chunks — is saved with the level, but left out when the level is exported (see Formats::LevelFile::IsEditorOnlyChunk()).

Public types

struct OverrideRefs
Tiles overridden by the level as tile references, see RemapTiles().
enum class ResizeFill : std::uint8_t { Empty, ExtendEdges, Repeat }
What the tiles of a layer that grows are, see ResizeLayer().

Public static variables

static std::int32_t DefaultTileIdSpace constexpr
Size of the tile ID space of a new level.
static std::int32_t ScriptTileIdLimit constexpr
Most tile IDs the scripting API can address.
static std::uint32_t LayerStateChunk constexpr
Chunk with the editor state of the layers.
static std::uint32_t LegacyLayerStateChunk constexpr
Chunk with the editor state of the layers written by 3.9.0, a byte for each layer, only read.
static LevelFlags EventFlags constexpr
Level flags the events decide, the level is saved with them as GetFlagsFromEvents() has them.

Public static functions

static auto GetEmptyEvent() -> const Formats::EventRecord&
Returns the empty event, as stored for a tile without any event.
static auto IsEmptyEvent(const Formats::EventRecord& event) -> bool
Returns true if an event is the empty one, which doesn't have to be stored.
static auto AreEventsEqual(const Formats::EventRecord& a, const Formats::EventRecord& b) -> bool
Returns true if two events are written the same.
static void NormalizeEvent(Formats::EventRecord& event)
Brings an event to the form the document keeps, without the bits the writer derives.
static auto GetProblemDescription(DocumentProblem problem) -> StringView
Returns a problem of Validate() as a text of a log, it isn't translated.

Constructors, destructors, conversion operators

LevelDocument()
Creates an empty document, without any layer.

Public functions

void Clear()
Clears the document.
void CreateNew(StringView tileSet, std::int32_t tileCount, Vector2i size)
Makes a new level of a given size with a tile set.
auto Load(Stream& s, ITileSetLibrary* tileSets) -> bool
Loads a level from a stream.
auto Save(Stream& s, bool exportOnly = false, std::int32_t compressionLevel = 9, LevelFlags extraFlags = LevelFlags::None) const -> bool
Saves the level to a stream.
auto GetSpriteLayerIndex() const -> std::int32_t
Returns the index of the sprite layer, or -1 if there is none.
auto GetEventGridSize() const -> Vector2i
Returns the size of the event grid, which is the size of the sprite layer.
auto GetAnimatedTilesOffset() const -> std::int32_t
Returns the tile ID of the first animated tile, as the file stores it.
auto GetSourceBaseId(std::uint8_t source) const -> std::int32_t
Returns the first tile ID of a source, or -1 if the source has no fixed range.
auto GetSourceTileCount(std::uint8_t source) const -> std::int32_t
Returns the number of tiles of a source, or -1 if it isn't known.
auto ToTileId(const TileRef& tile) const -> std::int32_t
Converts a tile reference to the tile ID the file stores.
auto FromTileId(std::int32_t tileId, std::uint8_t flags) const -> TileRef
Converts a tile ID the file stores to a tile reference.
auto MakeAnimatedTileRecord(std::int32_t index) const -> Formats::AnimatedTileRecord
Makes an animated tile as the file stores it, with tile IDs instead of tile references.
auto CaptureOverrideRefs() const -> OverrideRefs
Returns the tiles overridden by the level as tile references.
auto RemapTiles(const OverrideRefs& overrides, Function<bool(TileRef&)>& remap) -> std::int32_t
Changes the tile references of the whole level after its tile sets changed.
auto ResizeLayer(std::int32_t layer, Vector2i size, Vector2i offset, ResizeFill fill) -> bool
Resizes a layer, its tiles move by an offset.
auto GetStaticTileCount() const -> std::int32_t
Returns the number of tiles of the default tile set and all the extra tile sets, or -1 if it isn't known.
void FitTileIdSpace()
Makes the tile ID space larger if the tiles of the tile sets would reach the animated tiles.
auto GetFlagsFromEvents() const -> LevelFlags
Returns the flags of EventFlags the events of the level decide.
auto GetSavedFlags() const -> LevelFlags
Returns the flags the level is saved with, Flags with those the events decide.
auto IsTileAddressable(const TileRef& tile) const -> bool
Returns true if the level can save a tile by its ID.
auto GetEvent(std::int32_t x, std::int32_t y) const -> const Formats::EventRecord&
Returns the event at a tile of the grid, an empty one if there is none.
void SetEvent(std::int32_t x, std::int32_t y, const Formats::EventRecord& event)
Sets the event at a tile of the grid, an empty event removes it.
void SetEvents(ArrayView<const DocumentEvent> events)
Sets events at many tiles of the grid at once, an empty event removes the one there.
auto FindEvent(std::uint32_t cell) const -> std::size_t
Returns the position of the event of a tile in Events, or where it would be inserted.
auto FindChunk(std::uint32_t tag) const -> const Formats::ChunkRecord*
Returns the chunk with a tag, or nullptr.
void SetChunk(std::uint32_t tag, ArrayView<const std::uint8_t> data)
Sets the payload of a chunk, the chunk is added if it doesn't exist, and removed if the payload is empty.
void ReplaceChunk(std::uint32_t tag, SmallVector<std::uint8_t, 0>&& data)
Sets the payload of a chunk as SetChunk() does, taking the data instead of copying it.
auto GetLevelSettings() const -> Formats::LevelSettingsChunk::Settings
Returns the settings the properties of the level have no room for, see Formats::LevelSettingsChunk.
void SetLevelSettings(const Formats::LevelSettingsChunk::Settings& settings)
Writes the settings into their chunk, which is left out if all of them have their defaults.
void RemapLevelSettingsLayers(ArrayView<const std::int32_t> newIndices)
Keeps the water in front of the same layer after the layers moved.
auto Validate(DocumentProblem* problem = nullptr) const -> bool
Checks the document for problems that would make the level unloadable.

Public variables

LevelFlags Flags
Level flags, those of EventFlags as the level was loaded, they follow the events once it's saved.
Formats::LevelProperties Properties
Level properties.
std::uint32_t LevelPalette
Palette of the level, used only with LevelFlags::UseLevelPalette.
SmallVector<Formats::PaletteRecord, 0> AdditionalPalettes
Additional palettes.
std::int32_t DefaultTileCount
Number of tiles of the default tile set, or -1 if it isn't known.
SmallVector<Formats::ExtraTileSetRecord, 0> ExtraTileSets
Extra tile sets, their tiles follow the tiles of the default tile set.
SmallVector<Formats::TileDiffuseOverride, 0> DiffuseOverrides
Tiles with a diffuse overridden by the level, by their tile ID.
SmallVector<Formats::TileMaskOverride, 0> MaskOverrides
Tiles with a collision mask overridden by the level, by their tile ID.
SmallVector<String, 0> Texts
Level texts.
std::int32_t TileIdSpace
Size of the tile ID space, the animated tiles take its top.
SmallVector<DocumentAnimation, 0> Animations
Animated tiles.
SmallVector<DocumentLayer, 0> Layers
Layers in the order they are stored.
SmallVector<DocumentEvent, 0> Events
Events of the grid that aren't empty, sorted by their tile.
SmallVector<Formats::OffGridEventRecord, 0> OffGridEvents
Events placed anywhere, not aligned to the grid.
SmallVector<Formats::ChunkRecord, 0> Chunks
Chunks, in the order they are stored, except those the document holds itself.

Enum documentation

enum class Jazz2::Editor::LevelDocument::ResizeFill : std::uint8_t

What the tiles of a layer that grows are, see ResizeLayer().

Enumerators
Empty

Empty tiles

ExtendEdges

The tiles of the edges go on, the corners fill the corners

Repeat

The layer is repeated

Function documentation

void Jazz2::Editor::LevelDocument::CreateNew(StringView tileSet, std::int32_t tileCount, Vector2i size)

Makes a new level of a given size with a tile set.

The level has a foreground layer, the sprite layer and two background layers, all empty.

bool Jazz2::Editor::LevelDocument::Load(Stream& s, ITileSetLibrary* tileSets)

Loads a level from a stream.

The tile set library tells how many tiles the default tile set has, which is needed to tell the tiles of the extra tile sets apart. Without it, or if the tile set isn't found, those tiles are kept as raw IDs. Returns false if the stream doesn't hold a level in the game's own format or the level is damaged, the document is left empty then.

bool Jazz2::Editor::LevelDocument::Save(Stream& s, bool exportOnly = false, std::int32_t compressionLevel = 9, LevelFlags extraFlags = LevelFlags::None) const

Saves the level to a stream.

With exportOnly the editor-only data is left out, as it should be in a level that is published. extraFlags are saved along with the flags of the level, such as LevelFlags::NotEditable. Returns false if the level couldn't be written.

OverrideRefs Jazz2::Editor::LevelDocument::CaptureOverrideRefs() const

Returns the tiles overridden by the level as tile references.

The overrides are kept by tile ID, which moves with the tile sets before the tile. Taken before the tile sets change, they're put back by their new tile IDs by RemapTiles().

std::int32_t Jazz2::Editor::LevelDocument::RemapTiles(const OverrideRefs& overrides, Function<bool(TileRef&)>& remap)

Changes the tile references of the whole level after its tile sets changed.

remap changes a reference of the layers and the animated tiles in place, or returns false if its tile is gone. A reference past the end of its tile set is gone too. A tile that is gone is replaced by the empty tile and its overrides are dropped. Returns the number of tiles of the layers that were replaced.

bool Jazz2::Editor::LevelDocument::ResizeLayer(std::int32_t layer, Vector2i size, Vector2i offset, ResizeFill fill)

Resizes a layer, its tiles move by an offset.

The tile (0, 0) of the layer as it was goes to offset, tiles that end up outside of the layer are gone. With the sprite layer, events and the water level move with the tiles, events that end up outside of the level are gone. Returns false if the size is too small or too large.

LevelFlags Jazz2::Editor::LevelDocument::GetFlagsFromEvents() const

Returns the flags of EventFlags the events of the level decide.

As the converter of the original levels decides them: a race with laps has a warp with "Set Lap", Capture the Flag has a base, both only in a level for multiplayer, and a multiplayer start makes multiplayer spawn points. Events a generator makes don't count.

bool Jazz2::Editor::LevelDocument::IsTileAddressable(const TileRef& tile) const

Returns true if the level can save a tile by its ID.

A tile of the tile sets at or past the first animated tile can't be, its ID would be read as an animated tile or wouldn't fit (see GetAnimatedTilesOffset()), the space has to grow first. The empty tile, animated tiles and raw tile IDs always can be.

void Jazz2::Editor::LevelDocument::SetEvents(ArrayView<const DocumentEvent> events)

Sets events at many tiles of the grid at once, an empty event removes the one there.

events have to be sorted by their tile, each tile at most once. They're merged into Events in a single pass, which is much faster than setting them one by one when there are many.

void Jazz2::Editor::LevelDocument::RemapLevelSettingsLayers(ArrayView<const std::int32_t> newIndices)

Keeps the water in front of the same layer after the layers moved.

newIndices has the new index of each layer by its old one, -1 for a removed layer, the water in front of one is in front of the next one behind it.

bool Jazz2::Editor::LevelDocument::Validate(DocumentProblem* problem = nullptr) const

Checks the document for problems that would make the level unloadable.

Returns false and the first problem found if there is any, the editor shows it translated, see GetProblemDescription() for the text of a log.

Variable documentation

static std::uint32_t Jazz2::Editor::LevelDocument::LayerStateChunk constexpr

Chunk with the editor state of the layers.

u8 version (1), varuint number of layers, varuint bytes of each layer (at least 1), then the bytes of each layer in file order, the first being DocumentLayer::EditorFlags, the second, if there are 2 at least, DocumentLayer::EditorOpacity. A newer version may add bytes to each layer, a reader skips those it doesn't know.