Jazz2::Editor::EventCatalog class

All events the editor knows, how they are shown and how their parameters are edited.

The parameters are described as the game reads them — by the actors the events spawn and the code that handles the tiles and areas — not as the converter of the original levels writes them, so they are edited as the game understands them.

Events can be described from outside of the game too, in JSON (see LoadExtensions()): new ones that a script of a level reacts to, or ones the game knows that a script uses in another way. Those of the level replace those of event packs, which replace those of the game.

Public static variables

static std::uint16_t FirstOriginalPickType constexpr
First type of the list that stands for an event of the original game, see GetPickedOriginal().
static std::int32_t MaxContentsDepth constexpr
How deep events inside of events are followed, as a crate in a crate, see ForEachContents().

Public static functions

static auto LoadExtensions(StringView json, StringView source, EventExtensionScope scope) -> std::int32_t
Adds descriptions of events written in JSON.
static auto LoadMlleEvents(StringView script, StringView source, EventExtensionScope scope) -> std::int32_t
Adds the descriptions of events of the original game that MLLE keeps in a level script.
static auto GetPickedOriginal(EventType type) -> std::uint8_t
Returns the number of the event of the original game a type of the list stands for, or 0.
static auto IsHidden(const EventDescriptor* descriptor) -> bool
Returns true if the script of the level hides an event from the list, see LoadMlleEvents().
static void ClearExtensions(EventExtensionScope scope)
Removes all descriptions of events added in a scope, and the errors found in them.
static auto GetExtensionErrors() -> ArrayView<const EventExtensionError>
Returns what was wrong with the descriptions of events from outside of the game, until they're cleared.
static auto GetRevision() -> std::uint32_t
Returns a number that changes whenever events are described or not anymore, or errors are found, descriptions found before are invalid then.
static auto IsExtension(const EventDescriptor* descriptor) -> bool
Returns whether an event is described from outside of the game.
static auto IsLevelExtension(const EventDescriptor* descriptor) -> bool
Returns true if an event is described by the level being edited, by its script (see LoadMlleEvents()).
static auto Find(EventType type) -> const EventDescriptor*
Returns the description of an event, or nullptr if it's not known.
static auto Find(EventType type, const std::uint8_t* params) -> const EventDescriptor*
Returns the description of a placed event, or nullptr if it's not known.
static auto FindByKey(StringView key) -> const EventDescriptor*
Returns the description of an event by its key, or nullptr.
static auto MakeTextPreview(StringView text, std::size_t maxLength) -> String
Returns a level text as a single line to show, at most maxLength bytes long.
static auto GetAll() -> ArrayView<const EventDescriptor* const>
Returns all described events.
static auto GetCategoryName(EventCategory category) -> StringView
Returns the name of a category, translated.
static auto ReadField(const Formats::EventRecord& event, const EventParamField& field) -> std::int32_t
Reads a parameter of an event.
static void WriteField(Formats::EventRecord& event, const EventParamField& field, std::int32_t value)
Writes a parameter of an event, the value is clamped to the range of the field.
static auto MakeDefault(EventType type) -> Formats::EventRecord
Makes a new event of a type with the default values of its parameters.
static auto ReadString(const Formats::EventRecord& event, const EventParamField& field, char* buffer, std::size_t bufferSize) -> StringView
Reads a text parameter.
static auto FindPreviewCase(const EventDescriptor& descriptor, const Formats::EventRecord& event) -> const EventPreviewCase*
Returns how an event looks by the value of the field of EventDescriptor::PreviewCases, or nullptr if no case is for it.
static auto IsFieldVisible(const EventDescriptor& descriptor, std::size_t fieldIndex, const Formats::EventRecord& event) -> bool
Returns whether a field, by its index, is shown for an event — it isn't hidden and the condition on another field holds.
static auto ToDisplayValue(const EventParamField& field, std::int32_t value) -> std::int32_t
Returns a value as it's shown, multiplied by EventParamField::DisplayScale.
static auto FromDisplayValue(const EventParamField& field, std::int32_t displayValue) -> std::int32_t
Returns the value of a shown one, the closest step of EventParamField::DisplayScale.
static auto GetContentsDescriptor(const EventDescriptor& descriptor, const EventParamField& contentsField, const Formats::EventRecord& event) -> const EventDescriptor*
Returns the description of the event inside of a ParamType::Contents field, or nullptr if there's none or it isn't known.
static auto GetContents(const EventDescriptor& descriptor, const EventParamField& contentsField, const Formats::EventRecord& event) -> Formats::EventRecord
Returns the event inside of a ParamType::Contents field as an event of its own.
static void SetContents(const EventParamField& contentsField, Formats::EventRecord& event, const Formats::EventRecord& contents)
Stores the parameters of the event inside back into a ParamType::Contents field.
static auto FitsInContents(const EventParamField& contentsField, const EventParamField& innerField) -> bool
Returns whether a field of the event inside fits into the bytes of a ParamType::Contents field.
static void SetContentsType(const EventDescriptor& descriptor, const EventParamField& typeField, Formats::EventRecord& event, std::uint16_t type)
Writes the type of the event inside, and gives it the parameters of a new event of the type.
template<class Callback>
static auto ForEachContents(const EventDescriptor& descriptor, Formats::EventRecord& event, Callback&& callback, std::int32_t depth = 0) -> bool
Calls a function for an event and for each event inside of it, as a crate has one, down to MaxContentsDepth.
static auto MirrorParams(const EventDescriptor* descriptor, std::uint8_t* params, bool horizontal) -> bool
Changes the parameters of an event as mirroring it horizontally or vertically does.
static auto MirrorParams(const EventDescriptor* descriptor, Formats::EventRecord& event, bool horizontal) -> bool
static auto CanMirror(const EventDescriptor* descriptor) -> bool
Returns whether mirroring changes any parameter of an event of a description.
static auto SwapTeamParams(const EventDescriptor* descriptor, std::uint8_t* params, std::int32_t first = 0, std::int32_t second = 1) -> bool
Swaps two teams, by their numbers, in the fields marked as teams, returns true if anything changed.

Constructors, destructors, conversion operators

EventCatalog() deleted

Function documentation

static std::int32_t Jazz2::Editor::EventCatalog::LoadExtensions(StringView json, StringView source, EventExtensionScope scope)

Adds descriptions of events written in JSON.

The text is an object describing one event, an array of them, or an object with such an array in "Events", the format is described in Format of event descriptions. Keys are case-sensitive, the names given as values aren't.

An event with an "Original" in place of the "Type" is an event of the original game the game has no use for and keeps as EventType::PassthroughEvent for the scripts of the level, by its number there.

The range of a number is cut to -16777216 to 16777216, the number box edits it as a float, which holds whole numbers exactly only up to that. A value of a wrong type is taken as missing. What's wrong is logged with source, kept in GetExtensionErrors() and left out. Returns the number of events added.

static std::int32_t Jazz2::Editor::EventCatalog::LoadMlleEvents(StringView script, StringView source, EventExtensionScope scope)

Adds the descriptions of events of the original game that MLLE keeps in a level script.

Each is a line ///@Event <number>=<name>|<+ or ->|<category>|<label>|<label>|<parameters>... as in JCS.ini, a parameter Name:8 of 8 bits, Name:-8 signed, Name:c1 a check box or Name:{A,B,C}2 with named values. They're added as with "Original" (see LoadExtensions()), so they describe the passthrough events with their numbers, and they're offered in the list as well (see GetPickedOriginal()). A line ///@Event <number>= alone hides the event of the original game from the list, as MLLE does, so the event it becomes here is found only by searching (see IsHidden()). Returns the number of events added.

static std::uint8_t Jazz2::Editor::EventCatalog::GetPickedOriginal(EventType type)

Returns the number of the event of the original game a type of the list stands for, or 0.

The events of the original game the script of the level describes are offered by types of their own, from FirstOriginalPickType on. MakeDefault() makes one as it's placed.

static bool Jazz2::Editor::EventCatalog::IsExtension(const EventDescriptor* descriptor)

Returns whether an event is described from outside of the game.

The editor knows how the game uses the parameters of its own events — how they look, what handles they have in the level — that's used only while an event isn't described from outside of the game.

static const EventDescriptor* Jazz2::Editor::EventCatalog::Find(EventType type, const std::uint8_t* params)

Returns the description of a placed event, or nullptr if it's not known.

A passthrough event (EventType::PassthroughEvent) is described as the event of the original game it keeps, if it is (see "Original" in LoadExtensions()). So is an event of the game with the parameters the converter makes of a described event of the original game, the parameters of the original are in its last bytes then.

static String Jazz2::Editor::EventCatalog::MakeTextPreview(StringView text, std::size_t maxLength)

Returns a level text as a single line to show, at most maxLength bytes long.

Its parts are joined by a slash, the control characters the original texts have are left out and line breaks become spaces, so it takes a single line of the font. A longer one is cut and ends with three dots.

static Formats::EventRecord Jazz2::Editor::EventCatalog::MakeDefault(EventType type)

Makes a new event of a type with the default values of its parameters.

A type that stands for an event of the original game (see GetPickedOriginal()) makes the event as the converter makes it, the passthrough event that keeps it or the event of the game it becomes.

static Formats::EventRecord Jazz2::Editor::EventCatalog::GetContents(const EventDescriptor& descriptor, const EventParamField& contentsField, const Formats::EventRecord& event)

Returns the event inside of a ParamType::Contents field as an event of its own.

Its type is the one of the field EventParamField::ContentsTypeField, its parameters are the bytes of the field moved to the start, the rest of them zero. Its fields are read and written as of any event then, and stored back by SetContents().

static void Jazz2::Editor::EventCatalog::SetContentsType(const EventDescriptor& descriptor, const EventParamField& typeField, Formats::EventRecord& event, std::uint16_t type)

Writes the type of the event inside, and gives it the parameters of a new event of the type.

The parameters of the event inside mean something else for another type, so they are reset only when the type changes. A field that no ParamType::Contents field takes its type from is just written.

template<class Callback>
static bool Jazz2::Editor::EventCatalog::ForEachContents(const EventDescriptor& descriptor, Formats::EventRecord& event, Callback&& callback, std::int32_t depth = 0)

Calls a function for an event and for each event inside of it, as a crate has one, down to MaxContentsDepth.

The function is called as bool(const EventDescriptor&, Formats::EventRecord&) with an event inside as an event of its own (see GetContents()), and returns true if it changed it; a changed event inside is stored back into the one it's in. The events inside are taken as they were before the function changed the event they're in. Descriptions of events from outside of the game can name each other as what's inside, the depth is what ends it then. Returns true if anything changed.

static bool Jazz2::Editor::EventCatalog::MirrorParams(const EventDescriptor* descriptor, std::uint8_t* params, bool horizontal)

Changes the parameters of an event as mirroring it horizontally or vertically does.

Each field changes as its EventParamField::MirrorX or EventParamField::MirrorY says — the way a spring launches, the side a paddle is mounted on, speeds, offsets. The event inside a crate is mirrored too. Positions measured from the edges of the level don't change. Returns true if anything changed.

static bool Jazz2::Editor::EventCatalog::MirrorParams(const EventDescriptor* descriptor, Formats::EventRecord& event, bool horizontal)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.