Jazz2::Editor::SmartTileModel class

Learns how the tiles of a tile set fit together, from the levels that use it.

Nothing has to be set up: every level that uses the tile set as its default one is read, and for each tile of the tile set it's counted which of the 8 tiles around it weren't empty, and which tiles were next to it on the right and below. A cell to fill whose neighbors are known then gets the tile the levels used the most for the same neighbors, the one that also goes well with the tiles next to it — grass at the top of ground, its edges at its sides, corners and slopes where the levels have them.

The levels are read on a thread of their own where there are threads, otherwise a few at a time from Update(), so the editor doesn't stop for it either way; what they tell is taken in from Update() a little at a time. What each level told is kept in a cache file, Cache/Editor/Adjacency/<tile set>-<hash>.adj, by the path, the size and the time of the level, so only levels changed, added or removed since are read again — and so is everything if the tile set changes. The cache is written as the levels are read too, so the levels read already aren't read again if the editor is closed before all of them are.

The level being edited counts more than the others, as it is in the editor (see LearnDocument()), so the tiles it uses come first. It's learned a band of rows at a time, a few milliseconds a frame, and only the bands that changed are learned again.

The lists the tiles are picked from are sorted again only for the neighbors a tile is picked for, when what was learned of them changed. Tiles past the end of the tile set, of levels saved with an older version of it, are never learned, so they're never picked.

Public types

enum Neighbor : std::uint8_t { UpLeft = 0x01, Up = 0x02, UpRight = 0x04, Left = 0x08, Right = 0x10, DownLeft = 0x20, Down = 0x40, DownRight = 0x80 }
Bits of the neighbors of a cell that aren't empty.

Public static functions

static auto IsModelTile(const TileRef& tile) -> bool
Returns whether a tile is one the model picks from, of the tile set and not animated.

Constructors, destructors, conversion operators

SmartTileModel()
~SmartTileModel()
SmartTileModel(const SmartTileModel&) deleted
SmartTileModel(SmartTileModel&& other)

Public functions

auto operator=(const SmartTileModel&) -> SmartTileModel& deleted
auto operator=(SmartTileModel&& other) -> SmartTileModel&
void Request(StringView tileSet, ITileSetLibrary& library)
Starts learning a tile set, unless it's the one learned already.
void Reset()
Forgets everything learned, the next Request() learns the tile set again, as after it changed.
void Update()
Takes in what the levels read tell and reads more of them without threads, call it every frame.
auto IsReady() const -> bool
Returns true if all levels were read.
auto GetTileSet() const -> StringView
Returns the tile set learned.
auto GetLevelCount() const -> std::int32_t
Returns the number of levels learned from, not counting the one being edited.
auto GetProgress() const -> float
Returns how far reading the levels is, from 0 to 1.
auto CanPick() const -> bool
Returns true if there's anything to pick tiles from, levels learned from or rules.
void AddLevel(const LevelDocument& document, std::uint32_t weight)
Learns from a level, how many times it counts is given by weight.
void LearnDocument(const LevelDocument& document, std::uint32_t revision)
Learns from the level being edited, it counts more than the others.
auto Pick(std::uint8_t neighbors, bool spriteLayer, const TileRef* left, const TileRef* up, const TileRef* right, const TileRef* down, std::uint32_t hash, TileRef& result, const TileRef* keep = nullptr) -> bool
Picks a tile of the tile set for a cell.
auto GetSurfaceUsage(const TileRef& tile) -> std::uint32_t
Returns how many times the levels use a tile with nothing above it and something below it, as ground.
auto GetCount(std::uint8_t neighbors, bool spriteLayer, const TileRef& tile) const -> std::uint32_t
Returns how many times the levels use a tile with given neighbors that aren't empty.
auto Fits(std::uint8_t neighbors, bool spriteLayer, const TileRef& tile) const -> bool
Returns whether a tile fits its neighbors, it's one of the rule for them or the levels use it so.
auto GetRules() -> TerrainRules&
Returns the tiles chosen by hand, which are taken before those learned.
auto GetRightPair(const TileRef& left, const TileRef& right) const -> std::uint32_t
Returns how many times the levels have a tile right of another one.
auto GetDownPair(const TileRef& up, const TileRef& down) const -> std::uint32_t
Returns how many times the levels have a tile below another one.
auto Suggest(const TileRef* left, const TileRef* up, const TileRef* right, const TileRef* down, std::int32_t maxCount, SmallVectorImpl<TileRef>& result) -> std::int32_t
Suggests tiles for a cell by the tiles around it, the best first.
void GetTopTiles(std::uint8_t pattern, bool spriteLayer, std::int32_t maxCount, float minShare, SmallVectorImpl<TileRef>& result)
Returns the tiles the levels use the most for a pattern of neighbors as rules know it, the most first.
void GetCoverage(bool spriteLayer, std::uint8_t(&coverage)[256]) const
Returns how each pattern of neighbors as rules know it is covered, see TerrainRules::Reduce().
auto GetRevision() const -> std::uint64_t
Returns a number that changes whenever the tiles picked can, with what's learned or with the rules.

Function documentation

void Jazz2::Editor::SmartTileModel::LearnDocument(const LevelDocument& document, std::uint32_t revision)

Learns from the level being edited, it counts more than the others.

Call it whenever the model is used, it's cheap while revision doesn't change. A changed level is learned again at most every few seconds, a few milliseconds of each frame until all of it was gone through, and only the bands of rows of its layers that changed are learned again.

bool Jazz2::Editor::SmartTileModel::Pick(std::uint8_t neighbors, bool spriteLayer, const TileRef* left, const TileRef* up, const TileRef* right, const TileRef* down, std::uint32_t hash, TileRef& result, const TileRef* keep = nullptr)

Picks a tile of the tile set for a cell.

Parameters
neighbors Neighbors that aren't empty, see Neighbor
spriteLayer Whether it's for the sprite layer, levels use other tiles there than elsewhere
left Tile on the left already decided, or nullptr
up Tile above already decided, or nullptr
right Tile on the right, or nullptr
down Tile below, or nullptr
hash Picks among tiles about as good, so large areas aren't all the same tile
result The tile
keep Tile there now, kept if the levels use it with the same neighbors too, or nullptr

Returns false if nothing was learned yet.

std::int32_t Jazz2::Editor::SmartTileModel::Suggest(const TileRef* left, const TileRef* up, const TileRef* right, const TileRef* down, std::int32_t maxCount, SmallVectorImpl<TileRef>& result)

Suggests tiles for a cell by the tiles around it, the best first.

The tiles the levels have next to those around — right of the one on the left, below the one above, and so on — by how often, a tile next to more of them first. Neighbors that aren't tiles of the tile set are left out, the cell gets nothing if all of them are. Returns the number of tiles suggested.

void Jazz2::Editor::SmartTileModel::GetTopTiles(std::uint8_t pattern, bool spriteLayer, std::int32_t maxCount, float minShare, SmallVectorImpl<TileRef>& result)

Returns the tiles the levels use the most for a pattern of neighbors as rules know it, the most first.

Only what was learned, the rules aren't taken into account, see TerrainRules::Reduce(). A tile used less than a part of how much the first one is, by minShare, is left out.

void Jazz2::Editor::SmartTileModel::GetCoverage(bool spriteLayer, std::uint8_t(&coverage)[256]) const

Returns how each pattern of neighbors as rules know it is covered, see TerrainRules::Reduce().

0 not at all, 1 by tiles learned from the levels, 2 by a rule of the current terrain. Only the 47 patterns rules can be for are filled in.