Scriptelizer

Skript-Anleitung

Ein Skript ist ein kleines JavaScript-Programm, das Minecraft-Blöcke platziert. Diese Anleitung behandelt, wie du eines schreibst, im Browser ausführst und im öffentlichen Katalog veröffentlichst. Jeder mit einem Bloxelizer-Konto kann alle drei Dinge tun.

Einführung

Skripte laufen vollständig in deinem Browser, in einem isolierten JavaScript-Interpreter. Beim Experimentieren wird nichts hochgeladen: Du schreibst auf der einen Seite des Editors Code, drückst auf Ausführen, und die platzierten Blöcke erscheinen auf der anderen Seite in den 2D- und 3D-Viewern.

Der Sinn eines Skripts im Gegensatz zu einem einmaligen Build ist, dass andere es mit anderen Einstellungen ausführen können. Ein Skript, das Eingaben deklariert, bekommt neben dem Viewer ein Panel mit Steuerelementen, sodass jemand, der deinen Code nie gelesen hat, Größe, Material oder Seed ändern und das Ergebnis exportieren kann.

Wenn du zufrieden bist, drücke auf Speichern. Das Skript wird zur Prüfung eingereicht und bekommt nach der Freigabe eine eigene Seite im Skript-Katalog.

Zum Experimentieren brauchst du kein Konto

Skripte zu schreiben und auszuführen steht allen offen. Eine Anmeldung ist nur nötig, um ein Skript zu speichern und zur Prüfung einzureichen.

Dein erstes Skript

Öffne den Editor, ersetze den Inhalt durch das Folgende und drücke auf Ausführen. Es legt einen Steinboden von 8 mal 8 und setzt eine Fackel in die Mitte.

script.js
function main(context) {
  const { Creation } = context;

  const creation = Creation('My first build');

  creation.fillBox(0, 0, 0, 7, 0, 7, 'minecraft:stone');
  creation.setBlock(3, 1, 3, 'minecraft:torch');

  return { creation };
}

Drei Dinge sind bemerkenswert. Koordinaten sind Ganzzahlen, und y ist die senkrechte Achse, die Fackel sitzt also einen Block über dem Boden. fillBox nimmt zwei gegenüberliegende Ecken und füllt alles dazwischen, was viel schneller ist als eine Schleife. Und jedes Skript gibt seine Arbeit durch die Rückgabe von { creation } ab; ein Skript, das eine Creation baut, sie aber nie zurückgibt, erzeugt nichts.

Block-IDs sind die der Vanilla-Blöcke, mit dem Namensraum minecraft:. Der Editor ergänzt sie automatisch, sobald du in einem String zu tippen beginnst, du musst also selten eine nachschlagen.

Aufbau eines Skripts

Ein Skript ist einfaches JavaScript mit zwei besonderen Funktionen auf oberster Ebene. Wenn du möchtest, kannst du TypeScript-Syntax verwenden: Typen werden entfernt, bevor das Skript gespeichert oder ausgeführt wird.

main(context, inputs)

Erforderlich. Das läuft, wenn jemand auf Ausführen drückt. Es erhält das context-Objekt mit allen Helfern sowie die aktuellen Werte der von dir deklarierten Eingaben. Es muss ein Objekt mit einer creation zurückgeben und kann zusätzlich eine camera zurückgeben.

defineInputs(context)

Optional. Gib eine Map mit Eingabedefinitionen zurück, und der Editor zeigt für jede ein Steuerelement an. Die Werte kommen dann mit denselben Schlüsseln als zweites Argument bei main an.

script.js
function defineInputs(context) {
  const { Input } = context;

  return {
    size: Input.number({
      label: 'Size',
      description: 'Length of each side, in blocks',
      defaultValue: 8,
      min: 1,
      max: 64,
    }),
    material: Input.block({
      label: 'Material',
      defaultValue: 'minecraft:stone',
    }),
  };
}

function main(context, inputs) {
  const { Creation } = context;

  const creation = Creation('Platform');
  const last = inputs.size - 1;

  creation.fillBox(0, 0, 0, last, 0, last, inputs.material);

  return { creation };
}

defineInputs läuft, bevor Assets geladen werden

Beim Aufruf von defineInputs ist noch nichts geladen, daher sind dort nur die Listenaufrufe von Textures verfügbar, etwa listBlockNames() oder listMobModels(). Farbabfragen, Modelle und Sprites gehören in main.

Blöcke platzieren

Eine Creation sammelt Blockoperationen in der Reihenfolge, in der du sie ausführst. Spätere Schreibvorgänge in dieselbe Zelle gewinnen, du kannst also eine feste Form legen und dann hineinschneiden.

Du musst nicht am Ursprung bauen. Der Build wird beim Export auf seine eigene Bounding Box normalisiert, negative Koordinaten und beliebige für deine Rechnung praktische Versätze sind also in Ordnung.

Nimm für alles Große fillBox statt verschachtelter Schleifen: Eine Operation für eine Million Blöcke ist günstiger zu erzeugen, zu speichern und zu rendern als eine Million Operationen. Schleife nur dort, wo die Form wirklich von Block zu Block variiert.

Blockzustände

Treppen blicken in eine Richtung, Baumstämme haben eine Achse, Türen haben eine Hälfte. Das sind Blockzustände, und sie werden immer als Strings übergeben, auch "true" und "false".

script.js
// States are always strings, including "true" and "false".
creation.setBlock(0, 0, 0, 'minecraft:oak_stairs', {
  facing: 'east',
  half: 'bottom',
  shape: 'straight',
  waterlogged: 'false',
});

// Ask rather than guess: a bare banner has no placeable default.
const states = Textures.getPlacementStates('minecraft:white_banner');
creation.setBlock(2, 0, 0, 'minecraft:white_banner', states);

// Two-cell blocks place their other half for you, in the right
// direction: this one call leaves a whole bed facing east, so the
// head lands in the cell at x=5.
creation.setBlock(4, 0, 0, 'minecraft:red_bed', { facing: 'east' });

Die eigenen Standardwerte eines Blocks sind oft nicht platzierbar, was der häufigste Grund dafür ist, dass ein Einzelzellen-Block im Viewer falsch aussieht. Textures.getPlacementStates gibt die Zustände zurück, mit denen ein Block auf dem Boden stehen kann, und Textures.getStateOptions listet jeden Zustand auf, den ein Block akzeptiert, samt seinen gültigen Werten. Nutze sie, statt aus dem Blocknamen zu raten.

Das Rendering eines Blocks kann über seine Zelle hinausreichen

Ein stehendes Banner ist ein Block, aber sein Stoff wird etwa 1,6 Blöcke über der Zelle gezeichnet, in der es sitzt. Das ist ein Rendering, kein Block: Es verändert weder die Schichtzahl noch die Materialliste noch die Bauhöhe, ein Banner auf der obersten Schicht lässt den Build also nur eine Schicht über dem hoch, worauf es steht.

Blöcke aus zwei Zellen werden ganz platziert

Türen, Betten und hohe Blumen belegen zwei Zellen. Du platzierst eine, und setBlock fügt die andere Hälfte selbst hinzu, übernimmt deine Zustände und setzt den Kopf eines Betts an das Ende, zu dem es zeigt. Um bewusst nur eine Hälfte zu platzieren, benenne sie: Mit { half: 'upper' } oder { part: 'head' } wird nur diese platziert.

Eingaben

Jeder Helfer auf Input erzeugt ein Steuerelement. Der Typ des Werts, der bei main ankommt, ergibt sich aus dem verwendeten Helfer.

HelferWert in mainTypspezifische Optionen
Input.numbernumbermin, max, step
Input.stringstringdefaultValue
Input.booleanbooleandefaultValue
Input.selectstringoptions: string[] | { value, label }[]
Input.multiselectstring[]options: string[]
Input.blockstringoptions: Block-IDs (Standard ist jeder Block)
Input.fileScriptFile | nullaccept, required, paintable, allowMultipleFiles

Optionen, die jede Eingabe akzeptiert

OptionTypBeschreibung
labelstringBeschriftung des Steuerelements. Erforderlich.
descriptionstringHilfetext unter dem Steuerelement.
defaultValuevariesWert, der gilt, bevor der Betrachter etwas anfasst.
folderstringGruppiert dieses Steuerelement mit anderen im selben Ordner.
ordernumberSortierposition innerhalb eines Ordners. Niedrigere Werte erscheinen zuerst.
visibleWhen{ input, in?, notIn? }Blendet das Steuerelement aus, außer eine andere Eingabe hat einen dieser Werte.
resetsInputsstring[]Setzt diese Eingaben auf ihre Standardwerte zurück, wenn sich diese ändert.
resetValuesByOptionRecord<string, Record<string, unknown>>Voreingestellte Werte, die statt der Standardwerte gelten, nach dem Wert dieser Eingabe geordnet.

folder und order lohnen sich, sobald ein Skript mehr als eine Handvoll Steuerelemente hat, und visibleWhen hält ein Panel ehrlich, wenn ein Skript sich verzweigt: Eine Eingabe, die nur in einem Modus eine Rolle spielt, sollte im anderen nicht sichtbar sein.

Dateien und Bilder

Skripte haben keinen Netzwerkzugriff, daher kommt alles von außen über eine Dateieingabe herein. Eine Datei kommt als ScriptFile an: name, type, size, dazu text für Textdateien, dataUrl und imageData für Bilder.

imageData ist { width, height, data }, wobei data flaches RGBA ist, vier Einträge pro Pixel, Zeilen von oben nach unten. Da Y in einem Build nach oben wächst, musst du meist den Zeilenindex spiegeln.

script.js
function defineInputs(context) {
  const { Input } = context;

  return {
    image: Input.file({
      label: 'Image',
      accept: 'image/*',
      paintable: true,
    }),
  };
}

function main(context, inputs) {
  const { Creation, Textures } = context;

  const creation = Creation('Pixel art');
  const image = inputs.image;
  if (!image || !image.imageData) return { creation };

  const { width, height, data } = image.imageData;

  for (let y = 0; y < height; y++) {
    for (let x = 0; x < width; x++) {
      const at = (y * width + x) * 4;
      if (data[at + 3] < 128) continue; // Skip transparent pixels.

      const block = Textures.findClosestBlockToColor(
        data[at],
        data[at + 1],
        data[at + 2],
      );
      // Image rows run top-down, Y runs up, so flip the row.
      creation.setBlock(x, height - 1 - y, 0, block);
    }
  }

  return { creation };
}

Wenn du bei einer Bildeingabe paintable: true setzt, bekommt der Betrachter einen In-App-Zeichner statt einer Dateiauswahl, was ein guter Standard für Skripte ist, bei denen das Bild eine Skizze statt eines Fotos ist.

Eine Dateieingabe mit einer Strukturdatei ist etwas Besonderes: Der Host parst sie für dich, bevor main startet, und Structures.getLoadedSchem() liefert die enthaltenen Blöcke zurück. Ohne Namen wird die Eingabe namens schematic aufgelöst; gib einen Eingabenamen an, um eine auszuwählen, wenn ein Skript mehrere Builds nimmt, wie es bei einem Diff der Fall ist.

script.js
function defineInputs(context) {
  const { Input } = context;

  // The host pre-parses a file input named exactly `schematic`.
  return {
    schematic: Input.file({ label: 'Build', accept: '.litematic,.schem,.nbt' }),
  };
}

function main(context) {
  const { Creation, Structures, Logger } = context;

  const creation = Creation('Doubled');
  const loaded = Structures.getLoadedSchem();

  if (!loaded.ok) {
    Logger.warn(loaded.error);
    return { creation };
  }

  for (const op of loaded.operations) {
    creation.setBlock(op.x * 2, op.y, op.z * 2, op.name, op.states);
  }

  return { creation };
}

Das Ergebnis einrahmen

Gib neben der Creation eine camera zurück, um zu wählen, wo der 3D-Viewer beginnt. Nützlich, wenn die interessante Seite eines Builds nicht die ist, auf der die Standardkamera landet.

return {
  creation,
  camera: {
    position: [40, 30, 40],
    target: [0, 8, 0],
  },
};

Blöcke markieren

Gib highlights zurück, damit der 3D-Viewer einen farbigen Rand um benannte Zellen zeichnet. Die Blöcke behalten ihre eigenen Modelle, sodass sich etwas über eine Zelle aussagen lässt, ohne den Build neu einzufärben: welche Blöcke ein Diff hinzugefügt hat, welche Zellen eine Prüfung markiert hat, welche ein Durchlauf berührt hat.

Jeder Eintrag ist ein Paar { color, blocks }, wobei color ein Hex-String wie #22c55e ist und blocks eine Liste von [x, y, z]-Zellen. Pro Ausführung werden bis zu acht Gruppen und 200.000 umrandete Zellen gezeichnet, und ein Eintrag, den der Viewer nicht lesen kann, wird übersprungen, statt das Skript scheitern zu lassen.

script.js
function main(context) {
  const { Creation } = context;

  const creation = Creation('Review');
  const added = [];

  creation.setBlock(0, 0, 0, 'minecraft:stone');
  added.push([0, 0, 0]);

  // Each block still renders as itself; only the border is coloured.
  return {
    creation,
    highlights: [{ color: '#22c55e', blocks: added }],
  };
}

Referenz: context

Sowohl defineInputs als auch main erhalten ein Context-Objekt. Entpacke daraus, was du brauchst, statt auf globale Variablen zuzugreifen.

function main(context, inputs) {
  const { Creation, Logger, Textures, Structures } = context;
  // ...
}
HelferZweck
CreationBaut die Ausgabe.
LoggerSchreibt in das Log-Panel des Editors.
TexturesBlockdaten: Namen, Farben, Zustände, Modelle, Mob- und Skin-Modelle.
StructuresVanilla-Jigsaw-Strukturen und die Schematic, die der Viewer liefert.
Tree, Trees, Rocks, GradientsFertige Generatoren, die Operationen zurückgeben.

Der Editor kennt all das

Vollständige Typdefinitionen werden mit dem Editor ausgeliefert. Wenn du über einen Helfer fährst oder Strg + Leertaste drückst, siehst du die genaue Signatur und Dokumentation direkt. Diese Seite behandelt die am häufigsten genutzten Teile.

Referenz: Creation

Creation(name?: string): CreationInstance

Erstellt das Objekt, in das dein Skript baut. Die meisten Skripte erstellen genau eines, ganz oben in main.

ParameterTypBeschreibung
namestringName, der in Exporte übernommen wird. Standard ist "Untitled".

Rückgabe eine neue Creation, in die Blöcke platziert werden.

creation.setBlock(x, y, z, name, states?): void

Platziert einen Block. Wird eine Zelle zweimal beschrieben, bleibt der spätere Schreibvorgang erhalten. Bei einem Block aus zwei Zellen wird auch die zweite Hälfte platziert, es sei denn, die übergebenen Zustände benennen bereits eine Hälfte.

ParameterTypBeschreibung
x, y, znumberPosition. Ganzzahlen; Y ist oben.
namestringBlock-ID, zum Beispiel minecraft:stone.
statesRecord<string, string>Blockzustände. Werte sind Strings, auch "true".
creation.setBlock(0, 0, 0, 'minecraft:oak_log', { axis: 'y' });
creation.fillBox(x1, y1, z1, x2, y2, z2, type): void

Füllt jede Zelle zwischen zwei Ecken. Nimm dies statt einer Schleife, wann immer der Block nicht variiert.

ParameterTypBeschreibung
x1, y1, z1numberEine Ecke, einschließlich.
x2, y2, z2numberDie gegenüberliegende Ecke, einschließlich.
typestring | { name, states }Block-ID oder ein Block mit Zuständen.
creation.fillBox(0, 0, 0, 15, 0, 15, {
  name: 'minecraft:oak_log',
  states: { axis: 'x' },
});
creation.addOperations(ops): void

Hängt Operationen gesammelt an. So bringen die integrierten Generatoren ihre Ausgabe in eine Creation.

ParameterTypBeschreibung
opsOperation[]Operationen, etwa die, die ein Generator zurückgibt.
creation.getOperations(): Operation[]

Gibt alles zurück, was bisher platziert wurde, sodass ein Skript seine eigene Ausgabe vor der Rückgabe prüfen oder nachbearbeiten kann.

creation.reset(): void

Verwirft alle Operationen und hinterlässt eine leere Creation.

Referenz: Input

Verfügbar im Context, der an defineInputs übergeben wird. Die vollständigen Optionstabellen findest du oben unter Eingaben.

Input.number(config) Input.string(config) Input.boolean(config) Input.select(config) Input.multiselect(config) Input.block(config) Input.file(config)

Jeder gibt eine typisierte Eingabedefinition zurück. Gib sie aus defineInputs mit dem Namen zurück, unter dem du sie in main lesen möchtest.

sourceEntity: Input.select({
  label: 'Entity',
  options: Textures.listMobModels().map((model) => model.id),
  visibleWhen: { input: 'sourceType', in: ['entity'] },
})

Referenz: Logger

Logger.info(...args) Logger.warn(...args) Logger.error(...args) Logger.debug(...args)

Schreibt eine Zeile in das Log-Panel unter dem Editor. Die Ausgabe ist auf 1.000 Zeilen pro Lauf begrenzt, logge also Zusammenfassungen statt einer Zeile pro Block.

Logger.info('placed', creation.getOperations().length, 'operations');

Referenz: Textures

Der größte Namensraum und der, der ein Skript von einem Formgenerator zu etwas macht, das über Minecraft Bescheid weiß. Nur die Listenaufrufe funktionieren innerhalb von defineInputs.

Blöcke auflisten

AufrufRückgabe
listBlockNames(mcVersion?)Jede Block-ID, optional auf eine Minecraft-Version beschränkt.
listPaletteBlocks()Volle, undurchsichtige, im Survival erhältliche Würfel: die Menge, auf der ein Farbabgleich landen kann.
listBuildableBlocks()Palettenblöcke, die auch an Ort und Stelle bleiben, ohne Sand, Zementpulver und Lichtquellen.
listModelBlocks()Blöcke, deren eigenes Modell zu einer Statue seiner selbst voxelisiert werden kann.
listItems()Jedes Item, für das es Sprite-Grafik gibt.
listMobModels()Mob-Modellvorlagen, als { id, displayName }.
listEntityModels()Dieselben Modelle, aus denen sich eine Statue lohnt, einschließlich des Rüstungsständers.
listPosePresets()Die Posen, in denen ein Mob gebaut werden kann, als { id, displayName }.
listMinecraftVersions()Die Versionen, nach denen listBlockNames filtern kann, älteste zuerst.

Farbabgleich

Textures.findClosestBlockToColor(r, g, b, palette?, options?): string

Findet den Block, dessen eingebackene Farbe einem RGB-Wert am nächsten ist. Bei gemusterten Blöcken kann der standardmäßige Durchschnitt eine Farbe sein, die in der Textur nirgends vorkommt, daher passt dominant bei allem Glasierten oder Gemusterten meist besser.

ParameterTypBeschreibung
r, g, bnumberFarbkomponenten, 0 bis 255.
palettestring[]Beschränkt die Suche auf diese Blöcke. Standard ist jeder Palettenblock.
options{ colorSource?, metric? }colorSource ist "average" oder "dominant"; metric ist "lab" oder "ciede2000".

Rückgabe die ID des nächstgelegenen Blocks.

const block = Textures.findClosestBlockToColor(200, 60, 40, palette, {
  colorSource: 'dominant',
  metric: 'ciede2000',
});
Textures.getBlockColor(blockName, colorSource?): { r, g, b } | null

Die Umkehrabfrage. Kombiniere sie mit findClosestBlockToColor, um einen Block an einen anderen anzupassen, etwa den Teppich, der einem Boden am nächsten kommt.

Rückgabe die Farbe des Blocks oder null, wenn er keine Farbdaten hat.

Zustände und Formen

Textures.getPlacementStates(blockName): Record<string, string> | null

Übergib diese an setBlock, statt einen Block ohne sie zu platzieren. Ein Modell, das seine Variante nach facing wählt, löst ohne diese Angabe zu nichts auf, Knöpfe haben standardmäßig face=wall und schweben, und lebende Korallen haben standardmäßig waterlogged=true.

Rückgabe Zustände, mit denen der Block auf dem Boden stehen kann, oder null.

Textures.getStateOptions(blockName): Record<string, string[]> | null

Kombiniere sie mit getPlacementStates, wenn es auf die Form ankommt. Eine Scheibe, ein Zaun oder eine Mauer ohne Anschluss wird als bloßer Pfosten gezeichnet, frage also die gewünschten Verbindungen an.

Rückgabe jeden Zustand, den der Block akzeptiert, und seine gültigen Werte.

Textures.getSecondPart(blockName): { states, offset } | null

Für Türen, Betten und hohe Blumen; null für alles, was für sich steht. setBlock platziert die zweite Hälfte bereits, nimm dies also nur, wenn ein Skript die Form kennen muss, die ein Block annimmt, etwa um zu prüfen, ob vor dem Platzieren genug Platz ist.

Rückgabe die Zustände und den Versatz der anderen Hälfte oder null.

Textures.getBlockTraits(blockName): BlockTraits | null

Für den Bau relevante Fakten zu einem Block, um zu entscheiden, ob er angeboten oder platziert wird. Besser, als aus Teilstrings des Blocknamens zu raten.

Rückgabe Flags wie BlockEntity, NeedsSupport und CreativeOnly.

Modelle und Texturen

Textures.getBlockModel(blockName, blockProperties?): BlockModel | null

Die rohe Modellstruktur, um einen Block zu einer größeren Statue seiner selbst zu voxelisieren. Entity-artige Blöcke wie Truhen und Betten kommen mit synthetisierter Geometrie zurück, die durch entityModel markiert ist; solche ganz ohne Geometrie, etwa Köpfe, geben null zurück.

Rückgabe die Elemente und Flächentexturen des Modells oder null.

Textures.sampleTextureAtUV(textureName, u, v, options?): [r, g, b, a] | null

Liest ein Pixel einer Textur. Ohne exact wird eine nicht quadratische Textur als Animationsstreifen behandelt, und ein unbekannter Name tastet stillschweigend die Atlas-Ecke ab, übergib es also, wenn eines von beiden möglich ist.

ParameterTypBeschreibung
textureNamestringEin Texturname aus den Flächen eines Modells.
u, vnumberKoordinaten von 0 bis 1.
options{ exact?: boolean }exact liest das eigene Rechteck der Textur und gibt null zurück, wenn es fehlt.
Textures.getTextureSize(textureName): { width, height } | null

Erlaubt dir, in der Auflösung zu voxelisieren, in der ein Block tatsächlich gezeichnet wurde: Vanilla-Sprites sind 16 mal 16, Ressourcenpakete können 32 oder 64 haben.

Rückgabe die Größe eines Einzelbilds oder null.

Textures.getItemSprite(itemId): { width, height, data } | null

Vor einem Lauf wird nur das Item geladen, das eine sourceItem-Eingabe nennt, die Anfrage nach einem anderen gibt also null zurück. Sprites werden bei einer Vorlage von 16 mit 64 Pixeln geliefert, mittle also jeden 4-mal-4-Block, statt einzelne Pixel zu lesen.

Rückgabe RGBA-Zeilen, oberste Zeile zuerst, oder null.

Mobs und Skins

Textures.getMobModel(name, options?): { blocks, size, sourceBounds } | null

Voxelisiert einen Mob zu platzierbaren Blöcken. Übergib die zurückgegebenen blocks einzeln an setBlock oder versetze sie vorher.

ParameterTypBeschreibung
namestringEine Modell-ID aus listMobModels oder listEntityModels.
options{ scale?, offset?, textureName?, palette?, pose? }Voxelmaßstab, Platzierungsversatz, die Blöcke, aus denen gebaut wird, und wie er steht.
Textures.listPosePresets(): Array<{ id, displayName }>

Gib eine ID direkt als pose zurück oder übergib die Winkel selbst: headTurn, headTilt, rightArmSwing, rightArmRaise, leftArmSwing, leftArmRaise, rightLegSwing und leftLegSwing, jeweils in Grad. Ein Swing ist bei positivem Wert nach vorn, ein Raise hebt den Arm vom Körper weg, und der Kopf dreht sich bei positivem Wert zur linken Seite des Mobs und neigt sich nach unten. Jedes Teil dreht sich um sein eigenes Gelenk, sodass nur ein Mob mit menschlichem Körperbau alles annimmt: Ein vierbeiniger Mob dreht seinen Kopf und steht ansonsten, wie er ist. Die Drehung wird auf das Blockraster neu abgetastet, eine in steilem Winkel gestellte Statue braucht daher einen größeren scale, um sauber zu bleiben.

Rückgabe die Posen, in denen ein Mob gebaut werden kann, für eine Auswahl.

Textures.getSkinModel(name, options): { blocks, size, sourceBounds } | null

Dasselbe für ein Spielermodell, texturiert mit einem Skin, den der Betrachter hochlädt.

ParameterTypBeschreibung
namestringEin Spielermodell aus getPlayerModels.
options{ textureFile, scale?, offset?, palette? }textureFile ist eine ScriptFile aus einer Dateieingabe mit dem Skin-Bild.

Referenz: Structures

Structures.getLoadedSchem(name?): { ok, operations?, error? }

Der Host parst jede Strukturdatei-Eingabe, bevor main läuft, in jedem vom Schematic-Importer unterstützten Format, bis zu vier pro Lauf. Prüfe ok, bevor du operations liest: Ein fehlender oder nicht lesbarer Build meldet seinen eigenen error, ohne dich die anderen zu kosten.

ParameterTypBeschreibung
namestringDie zu lesende Dateieingabe. Standard ist die mit dem Namen schematic oder die erste deklarierte.

Rückgabe die geparsten Blöcke der Schematic, die diese Eingabe enthält.

Structures.listLoadedSchems(): string[]

In der Reihenfolge, in der getLoadedSchem() sie auflöst, der erste Eintrag ist also das, was ein Aufruf ohne Namen zurückgibt.

Rückgabe die Eingabenamen, unter denen eine Schematic geparst wurde.

Structures.generate(options): Promise<string[]>

Erzeugt eine Vanilla-Jigsaw-Struktur wie ein Dorf oder einen Plünderer-Außenposten und rendert sie direkt.

ParameterTypBeschreibung
options.structureIdstringEin Strukturpool, z. B. "minecraft:village/plains/town_centers".
options.depthnumberWie viele Teile platziert werden.
options.radiusnumberMaximaler horizontaler Radius.
options.heightnumberMaximale vertikale Höhe.
const chunkIds = await Structures.generate({
  structureId: 'minecraft:village/plains/town_centers',
  depth: 7,
});

Referenz: Generatoren

Vier Namensräume liefern fertige Formen. Alle geben setBlock-Operationen zurück, die am Ursprung verankert sind, statt etwas zu zeichnen, sodass du ihre Ausgabe versetzen, filtern oder wiederholen kannst, bevor sie die Creation erreicht.

script.js
function main(context) {
  const { Creation, Trees, Rocks } = context;

  const creation = Creation('Grove');

  // Generators return operations rather than drawing anything themselves,
  // so you can filter or offset them before they reach the creation.
  creation.addOperations(Trees.generate({ species: 'Oak', seed: 1, count: 3, spread: 12 }));
  creation.addOperations(Rocks.generate({ formation: 'Boulder', seed: 7, size: 5 }));

  return { creation };
}
NamensraumErzeugtErkundung
TreesDetaillierte Bäume und Haine nach Art, mit Kronen, Ausschmückung und Ranken.Trees.species()
RocksFelsbrocken, Geoden und Basaltsäulen.Rocks.formations()
GradientsLineare, radiale und Vier-Ecken-Blockverläufe mit Dithering.options: kind, stops, dither, paletteFilter
TreeDer ältere, parametergesteuerte Baumgenerator.Tree.getDefaults()

Sandbox und Grenzen

Skripte laufen in einem isolierten QuickJS-Interpreter. Es gibt kein DOM, kein window, kein document, keine Timer und keinen Netzwerkzugriff. Ein Skript, das externe Daten braucht, nimmt eine Dateieingabe.

Während ein Skript läuft

GrenzeWert
Arbeitsspeicher128 MB
Laufzeit10 Minuten, danach wird der Lauf unterbrochen
Quelltextgröße im Editor1.000.000 Zeichen
Koordinatenbereich±30,000,000
Log-Ausgabe1.000 Zeilen, 2.000 Zeichen pro Zeile
Platzierte BlöckeUnbegrenzt

Beim Einreichen

Eingereichter Code wird auf dem Server erneut geprüft, und diese Regeln sind strenger als die des Editors.

  • Der kompilierte Code darf höchstens 100 KB groß sein. Ein sehr großes Skript lässt sich daher lokal ausführen, aber nicht veröffentlichen.
  • Der Code darf nichts von Folgendem enthalten: eval(, Function(, setTimeout, setInterval, XMLHttpRequest, fetch(, import(, require(, process., child_process, fs., globalThis, global., __proto__, constructor.constructor.
  • Identischer Code wird als Duplikat abgelehnt: Der Server bildet einen Hash des kompilierten Skripts, daher wird die wortgleiche Neuveröffentlichung fremder Arbeit nicht durchgehen.

Die Musterprüfung ist ein einfacher Textabgleich

Er parst deinen Code nicht, schlägt also auch in Kommentaren und Strings an, und eine harmlose Variable namens fetchRow wird abgelehnt, weil sie fetch( enthält. Benenne sie um und reiche erneut ein.

Ein Skript einreichen

Drücke im angemeldeten Zustand auf Speichern. Du wirst nach einem Titel und einer Beschreibung gefragt, und das Skript kommt in eine Prüfwarteschlange.

  1. Ein ausstehendes Skript ist nur für dich sichtbar. Seine Seite listet jede eingereichte Version mit ihrem Status auf.
  2. Nach der Freigabe erscheint das Skript im öffentlichen Katalog mit eigener Seite und Adresse, und jeder kann es ausführen.
  3. Erneutes Speichern erzeugt eine neue Version, die für sich geprüft wird. Die freigegebene Version bleibt in der Zwischenzeit live, sodass eine Änderung nie kaputt macht, was andere gerade nutzen.
  4. Du kannst deine eigenen Skripte jederzeit auf der Skriptseite löschen.

Vor dem Einreichen

  • Gib einen Titel mit bis zu 100 Zeichen und eine Beschreibung mit mindestens 10 Zeichen an, die sagt, was es baut und was die Eingaben tun.
  • Prüfe, dass es mit seinen Standardeingaben bis zum Ende läuft. Ein Skript, das nur mit einer bestimmten Datei funktioniert, lässt sich schwer freigeben.
  • Gib jeder Eingabe einen sinnvollen Standardwert, eine klare Beschriftung und einen Bereich, der keinen zu großen Build zum Rendern erzeugen kann.
  • Titel und Beschreibungen durchlaufen einen Inhaltsfilter, und Links in einer Beschreibung werden mit einer Sperrliste abgeglichen.

Name und Beschreibung stehen fest

Sobald ein Skript existiert, ändern spätere Speicherungen den Code und erzeugen eine Version. Sie benennen es nicht um, wähle also einen Titel, den du behalten möchtest.

Fehlerbehebung

Keine main-Funktion definiert

Das Skript wurde geparst, hat aber nie main deklariert. Deklariere es als Funktion auf oberster Ebene, nicht in einer anderen verschachtelt und nicht bedingt zugewiesen.

Ungültiger Block-Name im Skript

Ein Aufruf von setBlock oder fillBox hat etwas erhalten, das keine Block-ID als String ist. Das kommt meist von einer Abfrage, die danebengehen kann, etwa einem Palettenindex, der über das Array-Ende hinausging.

Ungültige Koordinate im Skript

Eine Koordinate war NaN, unendlich oder außerhalb von ±30.000.000. Fast immer eine Division durch null oder eine Eingabe, die zu NaN geparst wurde.

Das Skript läuft, aber nichts erscheint

Prüfe, dass main { creation } zurückgibt und dass die zurückgegebene Creation die ist, in die du Blöcke platziert hast.

Ein Block wird als einfacher Würfel oder bloßer Pfosten gerendert

Er wurde ohne brauchbare Zustände platziert. Nutze Textures.getPlacementStates und Textures.getStateOptions für die Verbindungen bei Scheiben, Zäunen und Mauern.

Noch etwas? Melde dich über die FAQ-Seite.