Instantanés de données

Mécanique des instantanés

Au début de chaque frame, l’hôte marshalle en une seule fois les données de l’instance en un instantané POD (en-tête de longueur fixe + pools de tableaux de longueur variable + pool de chaînes UTF-8), qu’il transmet à mtrRender avec le pointeur du bloc d’état. Les enveloppes typées du SDK (mtr::Vehicle, mtr::Pids, mtr::Lift, mtr::EyeCandy) fournissent sur ce bloc mémoire des accesseurs homonymes de ceux du Wrapper JS :

• Les chaînes sont retournées sous forme de mtr::StrView (data + len) ; convertissez avec .str() en std::string et testez la vacuité avec .empty() ; la vue n’est valable que durant l’appel render en cours.
• Dans les listes ordinaires, un index hors limites lève std::out_of_range (sémantique identique à l’IndexOutOfBounds côté Java).
• Ne conservez pas les pointeurs d’instantané ni les enveloppes d’une frame à l’autre.

Vehicle (véhicule)

Fourni par mtr::Vehicle, miroir des VehicleWrapper + NTETrainWrapper de JS :

Car (voiture)

StopList

Stop / correspondances / sorties

mtr::Stop est le miroir du VehicleWrapper.Stop de JS :

Modes et types de transport

Deux axes complémentaires, qui retournent exactement les mêmes valeurs que getTransportMode() / getTransportType() côté JS ; des scripts écrits dans des langues différentes peuvent donc partager la logique de mise en page :

• Mode (énumération mtr::TransportMode) : UNKNOWN / TRAIN / BOAT / CABLE_CAR / AIRPLANE, couvrant les quatre catégories de véhicules de base.
• Type (id sous forme de chaîne, constantes mtr::transport_type) : le nom en minuscules du mode de base ("train", "boat", "cable_car", "airplane"), augmenté des types de ligne étendus de MAGIC MTR Addon train_normal / train_light_rail / train_high_speed / train_metro / train_bus / train_tram / train_sbahn ; en cas d’échec d’analyse : "unknown" ou vue vide (données de serveurs anciens).

if (vehicle.getTransportType() == mtr::transport_type::TRAIN_METRO) { /* ... */ }

for (int i = 0; i < stop.interchange_count(); i++) {
    mtr::Stop::Interchange ic = stop.interchange(i);
    if (ic.getTransportType() == mtr::transport_type::TRAIN_HIGH_SPEED) { /* ... */ }
}

Pids (écran d’arrivées)

mtr::Pids est le miroir du PIDSWrapper de JS :

Arrivals / Arrival

Psd (portes palières)

mtr::Psd reflète le PSDWrapper JS (une entrée psdScripts — voir Types de scripts JS · Scripts PSD) :

PsdDoor (unité de porte)

PsdArrival (train à venir)

Reprend tous les accesseurs d’Arrival de Pids (destination / route_name / route_number / platform_name / arrival_time / departure_time / deviation / realtime / terminating / circular_state / route_id / platform_id / route_color / car_count / departure_index — voir Pids), et ajoute :

PsdRoute / PsdStop (lignes et stations)

PsdStation (l’enregistrement de gare, ABI 13)

JcmPsdSnapshot.station_offset (décalage d’octet 124 ; -1 = pas de gare — le champ était du remplissage en ABI 12) pointe l’enregistrement JcmPsdStation de 96 octets — les mêmes données que l’objet JS psd.stop() :

PsdStation et ses accesseurs de station imbriqués renvoient des objets absents, des chaînes vides ou des valeurs par défaut si un index ou un enregistrement est invalide, sans exception d’index. Pour construire un instantané hors de l’hôte, passez la taille réelle du tampon à mtr::Psd(snapshot, byteLength). Le constructeur compatible à pointeur seul exige un en-tête entièrement lisible et le tampon qu’il déclare ; un pointeur brut ne révèle pas la taille de l’allocation.

ABI 12 → 13 est purement additif (un champ de remplissage promu en place, aucune structure existante modifiée) : les modules ABI 6–12 continuent de se charger.

Lift (ascenseur)

mtr::Lift (combinaison instantané + enveloppe Java ; partie instantané) :

Les interfaces plus profondes — gestionnaire de rendu, gestionnaire de sons, visibilité, etc. — s’accèdent via le wrapper() de Api (l’ascenseur n’a pas de page de documentation JS dédiée ; l’enveloppe Java fait foi).

EyeCandy (décoration)

mtr::EyeCandy est le miroir de l’EyecandyBlockEntityWrapper :

Les détails de l’événement (joueur, objet en main, etc.) se lisent via Api :

mtr::Api api(ctx.input());
auto event = api.context().call("events").get("onBlockUse");
if (event.call("occurred").as<bool>()) {
    auto detail = event.call("detail");
    auto player = detail.call("player");
    auto item   = detail.call("item");
}

Le contexte de dessin de l’eyecandy, EyeCandyContext, fournit draw_model(model, matrices), play_sound(sound, volume, pitch), set_outline_shape(boxes, count) et set_collision_shape(boxes, count) (6 float par boîte ; les boîtes de collision conservent la limite de hauteur de 1,5 bloc appliquée côté Java, tout dépassement est validé et journalisé par l’hôte). L’ascenseur réutilise le même type de contexte (LiftContext = EyeCandyContext).

Types utilitaires

<mtr/util.hpp> fournit des utilitaires de carrousel et de suivi d’état adaptés au chemin chaud (zéro allocation) :

// "A|B|C" alterne un segment toutes les 40 ticks ; le changement de vue se résume à un calcul d'offset
mtr::CycleTracker dest{"KOWLOON|TSUEN WAN"};
StrView current = dest.value(vehicle.in_game_time());

Suivi de machine à états mtr::StateTracker<T> (miroir du StateTrackerJS amont ; l’horloge est passée explicitement — le game_time_millis() de l’instantané est l’équivalent naturel) : placez le champ dans State et effectuez un seul contrôle de transition par rendu :

struct State {
    mtr::StateTracker<Phase> phase;   // persiste d’une frame à l’autre
};

// dans render() :
if (s.phase.set_state(next, vehicle.game_time_millis())) {
    // true — première frame dans cet état (nouvelle sémantique amont prerelease.2)
}
double staying = s.phase.state_now_duration(vehicle.game_time_millis());
if (s.phase.changed_from_to(PHASE_IDLE, PHASE_ARRIVING)) { /* animation d’arrivée */ }

Ensuite : Dessin et canevas — comment dessiner ces données.