Scriptelizer

Guide des scripts

Un script est un petit programme JavaScript qui place des blocs Minecraft. Ce guide explique comment en écrire un, l'exécuter dans le navigateur et le publier dans le catalogue public. Toute personne ayant un compte Bloxelizer peut faire les trois.

Introduction

Les scripts s'exécutent entièrement dans votre navigateur, dans un interpréteur JavaScript isolé. Rien n'est envoyé pendant que vous expérimentez : vous écrivez du code d'un côté de l'éditeur, vous appuyez sur Exécuter, et les blocs qu'il place apparaissent dans les visionneuses 2D et 3D de l'autre côté.

L'intérêt d'un script, par rapport à une construction ponctuelle, est que d'autres personnes peuvent l'exécuter avec des réglages différents. Un script qui déclare des entrées obtient un panneau de contrôles à côté de la visionneuse, de sorte que quelqu'un qui n'a jamais lu votre code peut changer la taille, le matériau ou la graine et exporter le résultat.

Quand vous en êtes satisfait, appuyez sur Enregistrer. Le script est soumis à validation et, une fois approuvé, il obtient sa propre page dans le catalogue de scripts.

Pas besoin de compte pour expérimenter

Écrire et exécuter des scripts est ouvert à tous. Une connexion n'est nécessaire que pour enregistrer un script et le soumettre à validation.

Votre premier script

Ouvrez l'éditeur, remplacez ce qui s'y trouve par ce qui suit, puis appuyez sur Exécuter. Il pose un sol en pierre de 8 sur 8 et place une torche au milieu.

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 };
}

Trois choses sont à noter. Les coordonnées sont des entiers, et y est l'axe vertical, donc la torche se trouve un bloc au-dessus du sol. fillBox prend deux coins opposés et remplit tout ce qui se trouve entre eux, ce qui est bien plus rapide qu'une boucle. Et chaque script rend son travail en renvoyant { creation } ; un script qui construit une création sans la renvoyer ne produit rien.

Les identifiants de blocs sont ceux de vanilla, avec l'espace de noms minecraft:. L'éditeur les complète automatiquement dès que vous commencez à taper dans une chaîne, vous avez donc rarement besoin d'en chercher un.

Anatomie d'un script

Un script est du JavaScript pur avec deux fonctions spéciales de premier niveau. Vous pouvez utiliser la syntaxe TypeScript si vous préférez : les types sont retirés avant que le script soit enregistré ou exécuté.

main(context, inputs)

Obligatoire. C'est ce qui s'exécute quand quelqu'un appuie sur Exécuter. Elle reçoit l'objet context qui contient tous les utilitaires, ainsi que les valeurs actuelles des entrées que vous avez déclarées. Elle doit renvoyer un objet contenant une creation, et peut aussi renvoyer une camera.

defineInputs(context)

Facultative. Renvoyez une table de définitions d'entrées et l'éditeur affiche un contrôle pour chacune. Les valeurs arrivent ensuite en second argument de main, avec les mêmes clés.

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 s'exécute avant le chargement des ressources

Rien n'est encore chargé quand defineInputs est appelée : seuls les appels de listage de Textures y sont disponibles, comme listBlockNames() ou listMobModels(). Les recherches de couleurs, les modèles et les sprites relèvent de main.

Placer des blocs

Une création collecte les opérations sur les blocs dans l'ordre où vous les faites. Les écritures ultérieures dans la même cellule l'emportent : vous pouvez donc poser une forme pleine puis la creuser.

Vous n'avez pas besoin de construire à l'origine. La construction est normalisée sur sa propre boîte englobante à l'export : les coordonnées négatives et les décalages pratiques pour vos calculs ne posent donc aucun problème.

Pour tout ce qui est grand, préférez fillBox aux boucles imbriquées : une opération couvrant un million de blocs est moins coûteuse à produire, à stocker et à afficher qu'un million d'opérations. Ne bouclez que là où la forme varie vraiment d'un bloc à l'autre.

États de bloc

Les escaliers regardent dans une direction, les bûches ont un axe, les portes ont une moitié. Ce sont des états de bloc, et ils sont toujours passés sous forme de chaînes, y compris "true" et "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' });

Les valeurs par défaut d'un bloc ne sont souvent pas placables, ce qui est la raison la plus fréquente pour laquelle un bloc d'une seule cellule paraît incorrect dans la visionneuse. Textures.getPlacementStates renvoie les états qui permettent à un bloc de tenir sur le sol, et Textures.getStateOptions liste tous les états qu'un bloc accepte avec leurs valeurs valides. Utilisez-les plutôt que de deviner à partir du nom du bloc.

Le rendu d'un bloc peut dépasser sa cellule

Une bannière posée est un seul bloc, mais son tissu est dessiné en s'élevant d'environ 1,6 bloc au-dessus de la cellule où elle se trouve. C'est un rendu, pas un bloc : cela n'ajoute rien au nombre de couches, à la liste des matériaux ni à la hauteur de la construction, si bien qu'une bannière sur la couche du haut laisse la construction à une couche de haut au-dessus de ce qui la supporte.

Les blocs de deux cellules sont placés en entier

Les portes, les lits et les grandes fleurs occupent deux cellules. Vous en placez une et setBlock ajoute l'autre moitié lui-même, en reportant vos états et en mettant la tête d'un lit du côté vers lequel il est orienté. Pour placer volontairement une moitié seule, nommez-la : passer { half: 'upper' } ou { part: 'head' } ne place que celle-là.

Entrées

Chaque utilitaire de Input produit un contrôle. Le type de la valeur qui arrive dans main découle de l'utilitaire que vous avez employé.

UtilitaireValeur dans mainOptions propres au type
Input.numbernumbermin, max, step
Input.stringstringdefaultValue
Input.booleanbooleandefaultValue
Input.selectstringoptions: string[] | { value, label }[]
Input.multiselectstring[]options: string[]
Input.blockstringoptions: identifiants de blocs (tous les blocs par défaut)
Input.fileScriptFile | nullaccept, required, paintable, allowMultipleFiles

Options acceptées par toutes les entrées

OptionTypeDescription
labelstringLibellé du contrôle. Obligatoire.
descriptionstringTexte d'aide sous le contrôle.
defaultValuevariesValeur utilisée avant que le spectateur ne touche à quoi que ce soit.
folderstringRegroupe ce contrôle avec d'autres du même dossier.
ordernumberPosition de tri dans un dossier. Les plus petites valeurs s'affichent en premier.
visibleWhen{ input, in?, notIn? }Masque le contrôle sauf si une autre entrée a l'une de ces valeurs.
resetsInputsstring[]Réinitialise ces entrées à leurs valeurs par défaut quand celle-ci change.
resetValuesByOptionRecord<string, Record<string, unknown>>Valeurs prédéfinies à appliquer à la place des valeurs par défaut, selon la valeur de cette entrée.

folder et order valent la peine d'être utilisés dès qu'un script a plus d'une poignée de contrôles, et visibleWhen garde un panneau cohérent quand un script se ramifie : une entrée qui ne compte que dans un mode ne devrait pas être visible dans l'autre.

Fichiers et images

Les scripts n'ont pas accès au réseau : tout ce qui vient de l'extérieur passe donc par une entrée de fichier. Un fichier arrive sous forme de ScriptFile : name, type, size, plus text pour les fichiers texte, dataUrl, et imageData pour les images.

imageData vaut { width, height, data }, où data est un tableau RGBA à plat, quatre valeurs par pixel, les lignes allant de haut en bas. Comme Y monte dans une construction, il faudra généralement inverser l'indice de ligne.

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 };
}

Définir paintable: true sur une entrée d'image donne à la visionneuse un outil de dessin intégré à la place d'un sélecteur de fichier, ce qui est un bon choix par défaut pour les scripts où l'image est un croquis plutôt qu'une photo.

Une entrée de fichier contenant un fichier de structure est particulière : l'hôte l'analyse pour vous avant le démarrage de main, et Structures.getLoadedSchem() renvoie les blocs qu'il contient. Sans nom, elle résout l'entrée appelée schematic ; passez un nom d'entrée pour en choisir une quand un script prend plusieurs constructions, comme le fait un diff.

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 };
}

Cadrer le résultat

Renvoyez une camera à côté de la création pour choisir où la visionneuse 3D démarre. Utile quand le côté intéressant d'une construction n'est pas celui sur lequel tombe la caméra par défaut.

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

Marquer des blocs

Renvoyez highlights pour que la visionneuse 3D dessine une bordure colorée autour de cellules nommées. Les blocs gardent leurs propres modèles : on signale donc quelque chose sur une cellule sans repeindre la construction, par exemple quels blocs un diff a ajoutés, quelles cellules une vérification a signalées ou lesquelles une passe a touchées.

Chaque entrée est une paire { color, blocks }, où color est une chaîne hexadécimale comme #22c55e et blocks une liste de cellules [x, y, z]. Jusqu'à huit groupes et 200 000 cellules entourées sont dessinés par exécution, et une entrée que la visionneuse ne peut pas lire est ignorée au lieu de faire échouer le script.

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 }],
  };
}

Référence : context

defineInputs et main reçoivent toutes deux un objet context. Déstructurez-le pour obtenir ce dont vous avez besoin plutôt que d'utiliser des variables globales.

function main(context, inputs) {
  const { Creation, Logger, Textures, Structures } = context;
  // ...
}
UtilitaireRôle
CreationConstruit la sortie.
LoggerÉcrit dans le panneau de journal de l'éditeur.
TexturesDonnées de blocs : noms, couleurs, états, modèles, modèles de mobs et de skins.
StructuresLes structures jigsaw vanilla, et le schematic fourni par la visionneuse.
Tree, Trees, Rocks, GradientsGénérateurs prêts à l'emploi qui renvoient des opérations.

L'éditeur connaît tout cela

Les définitions de types complètes sont fournies avec l'éditeur : survoler un utilitaire ou appuyer sur Ctrl + Espace affiche la signature exacte et la documentation sur place. Cette page couvre les parties dont vous aurez le plus souvent besoin.

Référence : Creation

Creation(name?: string): CreationInstance

Crée l'objet dans lequel votre script construit. La plupart des scripts en font exactement un, au début de main.

ParamètreTypeDescription
namestringNom repris dans les exports. Par défaut « Untitled ».

Renvoie une nouvelle création dans laquelle placer des blocs.

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

Place un bloc. Écrire deux fois dans une cellule conserve la dernière écriture. Pour un bloc de deux cellules, la seconde moitié est placée aussi, sauf si les états que vous passez désignent déjà une moitié.

ParamètreTypeDescription
x, y, znumberPosition. Entiers ; Y est vers le haut.
namestringIdentifiant de bloc, par exemple minecraft:stone.
statesRecord<string, string>États du bloc. Les valeurs sont des chaînes, y compris "true".
creation.setBlock(0, 0, 0, 'minecraft:oak_log', { axis: 'y' });
creation.fillBox(x1, y1, z1, x2, y2, z2, type): void

Remplit chaque cellule entre deux coins. À préférer à une boucle dès que le bloc ne varie pas.

ParamètreTypeDescription
x1, y1, z1numberUn coin, inclus.
x2, y2, z2numberLe coin opposé, inclus.
typestring | { name, states }Identifiant de bloc, ou bloc avec états.
creation.fillBox(0, 0, 0, 15, 0, 15, {
  name: 'minecraft:oak_log',
  states: { axis: 'x' },
});
creation.addOperations(ops): void

Ajoute des opérations en masse. C'est ainsi que les générateurs intégrés placent leur sortie dans une création.

ParamètreTypeDescription
opsOperation[]Des opérations, comme celles qu'un générateur renvoie.
creation.getOperations(): Operation[]

Renvoie tout ce qui a été placé jusqu'ici, ce qui permet à un script d'inspecter ou de retraiter sa propre sortie avant de la renvoyer.

creation.reset(): void

Supprime toutes les opérations et laisse une création vide.

Référence : Input

Disponible sur le context passé à defineInputs. Voir Entrées ci-dessus pour les tableaux d'options complets.

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

Chacun renvoie une définition d'entrée typée. Renvoyez-les depuis defineInputs avec le nom sous lequel vous voulez les lire dans main.

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

Référence : Logger

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

Écrit une ligne dans le panneau de journal sous l'éditeur. La sortie est plafonnée à 1 000 lignes par exécution : consignez donc des résumés plutôt qu'une ligne par bloc.

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

Référence : Textures

Le plus grand espace de noms, et celui qui fait d'un script autre chose qu'un générateur de formes : quelque chose qui connaît Minecraft. Seuls les appels de listage fonctionnent dans defineInputs.

Lister les blocs

AppelCe qu'il renvoie
listBlockNames(mcVersion?)Chaque identifiant de bloc, éventuellement limité à une version de Minecraft.
listPaletteBlocks()Cubes pleins, opaques et obtenables en survie : l'ensemble sur lequel une correspondance de couleur peut tomber.
listBuildableBlocks()Les blocs de la palette qui restent aussi en place, sans le sable, la poudre de béton et les sources de lumière.
listModelBlocks()Les blocs dont le propre modèle peut être voxélisé en une statue d'eux-mêmes.
listItems()Tous les objets pour lesquels il existe un sprite.
listMobModels()Modèles de mobs, sous la forme { id, displayName }.
listEntityModels()Les mêmes modèles dont on peut faire une statue, y compris le support d'armure.
listPosePresets()Les poses dans lesquelles un mob peut être construit, sous la forme { id, displayName }.
listMinecraftVersions()Les versions par lesquelles listBlockNames peut filtrer, de la plus ancienne à la plus récente.

Correspondance de couleurs

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

Trouve le bloc dont la couleur calculée est la plus proche d'une valeur RGB. Sur les blocs à motifs, la moyenne par défaut peut être une couleur qui n'apparaît nulle part dans la texture : dominant est donc généralement la meilleure correspondance pour tout ce qui est émaillé ou à motifs.

ParamètreTypeDescription
r, g, bnumberComposantes de couleur, de 0 à 255.
palettestring[]Limite la recherche à ces blocs. Par défaut tous les blocs de la palette.
options{ colorSource?, metric? }colorSource vaut « average » ou « dominant » ; metric vaut « lab » ou « ciede2000 ».

Renvoie l'identifiant du bloc le plus proche.

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

La recherche inverse. Associez-la à findClosestBlockToColor pour faire correspondre un bloc à un autre, par exemple choisir le tapis le plus proche d'un sol.

Renvoie la couleur du bloc, ou null s'il n'a pas de données de couleur.

États et formes

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

Passez-les à setBlock plutôt que de placer un bloc nu. Un modèle qui choisit sa variante selon facing ne donne rien sans cet état, les boutons ont par défaut face=wall et flottent, et les coraux vivants ont par défaut waterlogged=true.

Renvoie les états qui permettent au bloc de tenir sur le sol, ou null.

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

Associez-la à getPlacementStates quand la forme compte. Une vitre, une barrière ou un muret sans rien à quoi se connecter est dessiné comme un simple poteau : demandez donc les connexions voulues.

Renvoie tous les états que le bloc accepte et leurs valeurs valides.

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

Pour les portes, les lits et les grandes fleurs ; null pour tout ce qui tient seul. setBlock place déjà la seconde moitié, n'utilisez donc ceci que quand un script a besoin de connaître la forme que prendra un bloc, par exemple pour vérifier qu'il y a de la place avant de le poser.

Renvoie les états et le décalage de l'autre moitié, ou null.

Textures.getBlockTraits(blockName): BlockTraits | null

Des informations utiles à la construction sur un bloc, pour décider de le proposer ou de le placer. Mieux que de deviner à partir de morceaux du nom du bloc.

Renvoie des indicateurs comme BlockEntity, NeedsSupport et CreativeOnly.

Modèles et textures

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

La structure brute du modèle, pour voxéliser un bloc en une plus grande statue de lui-même. Les blocs de type entité comme les coffres et les lits reviennent avec une géométrie synthétisée signalée par entityModel ; ceux qui n'ont aucune géométrie, comme les têtes, renvoient null.

Renvoie les éléments du modèle et les textures des faces, ou null.

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

Lit un pixel d'une texture. Sans exact, une texture non carrée est traitée comme une bande d'animation et un nom inconnu échantillonne silencieusement le coin de l'atlas : passez-le donc dès que l'un ou l'autre est possible.

ParamètreTypeDescription
textureNamestringUn nom de texture provenant des faces d'un modèle.
u, vnumberCoordonnées de 0 à 1.
options{ exact?: boolean }exact lit le rectangle propre de la texture et renvoie null s'il est absent.
Textures.getTextureSize(textureName): { width, height } | null

Permet de voxéliser à la résolution à laquelle un bloc a réellement été dessiné : les sprites vanilla font 16 sur 16, les packs de ressources peuvent faire 32 ou 64.

Renvoie la taille d'une image, ou null.

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

Seul l'objet nommé par une entrée sourceItem est chargé avant une exécution : en demander un autre renvoie donc null. Les sprites sont fournis en 64 pixels pour un graphisme conçu en 16 : faites donc la moyenne de chaque bloc de 4 sur 4 plutôt que de lire des pixels isolés.

Renvoie des lignes RGBA, la ligne du haut en premier, ou null.

Mobs et skins

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

Voxélise un mob en blocs que vous pouvez placer. Passez les blocks renvoyés à setBlock un par un, ou décalez-les d'abord.

ParamètreTypeDescription
namestringUn identifiant de modèle de listMobModels ou listEntityModels.
options{ scale?, offset?, textureName?, palette?, pose? }Échelle des voxels, décalage de placement, blocs avec lesquels le construire, et sa posture.
Textures.listPosePresets(): Array<{ id, displayName }>

Repassez directement un identifiant comme pose, ou passez vous-même les angles : headTurn, headTilt, rightArmSwing, rightArmRaise, leftArmSwing, leftArmRaise, rightLegSwing et leftLegSwing, chacun en degrés. Un balancement est vers l'avant quand il est positif, une élévation écarte le bras du corps, et la tête tourne vers la gauche du mob et s'incline vers le bas quand elle est positive. Chaque partie tourne autour de sa propre articulation : seul un mob construit comme une personne prend le tout, et un mob à quatre pattes tourne la tête et reste tel quel. La rotation est rééchantillonnée sur la grille de blocs, une statue en pose très inclinée demande donc une scale plus grande pour rester propre.

Renvoie les poses dans lesquelles un mob peut être construit, pour un sélecteur.

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

La même chose pour un modèle de joueur, texturé avec un skin que le spectateur importe.

ParamètreTypeDescription
namestringUn modèle de joueur provenant de getPlayerModels.
options{ textureFile, scale?, offset?, palette? }textureFile est un ScriptFile issu d'une entrée de fichier contenant l'image du skin.

Référence : Structures

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

L'hôte analyse chaque entrée de fichier de structure avant l'exécution de main, dans n'importe quel format pris en charge par l'importeur de schematics, jusqu'à quatre par exécution. Vérifiez ok avant de lire operations : une construction manquante ou illisible signale sa propre error sans vous priver des autres.

ParamètreTypeDescription
namestringL'entrée de fichier à lire. Par défaut celle nommée schematic, ou la première déclarée.

Renvoie les blocs analysés du schematic que contient cette entrée.

Structures.listLoadedSchems(): string[]

Dans l'ordre où getLoadedSchem() les résout, de sorte que la première entrée est ce que renvoie un appel sans nom.

Renvoie les noms d'entrée sous lesquels un schematic a été analysé.

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

Génère une structure jigsaw vanilla comme un village ou un avant-poste de pillards, et l'affiche directement.

ParamètreTypeDescription
options.structureIdstringUn pool de structures, par exemple « minecraft:village/plains/town_centers ».
options.depthnumberNombre de pièces à placer.
options.radiusnumberRayon horizontal maximal.
options.heightnumberHauteur verticale maximale.
const chunkIds = await Structures.generate({
  structureId: 'minecraft:village/plains/town_centers',
  depth: 7,
});

Référence : Generators

Quatre espaces de noms produisent des formes toutes prêtes. Tous renvoient des opérations setBlock ancrées à l'origine au lieu de dessiner quoi que ce soit, ce qui vous permet de décaler, filtrer ou répéter leur sortie avant qu'elle n'atteigne la création.

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 };
}
Espace de nomsGénèreDécouverte
TreesArbres et bosquets détaillés par espèce, avec canopées, ornements et lianes.Trees.species()
RocksRochers, géodes et colonnes de basalte.Rocks.formations()
GradientsDégradés de blocs linéaires, radiaux et à quatre coins, avec tramage.options: kind, stops, dither, paletteFilter
TreeL'ancien générateur d'arbres piloté par des paramètres.Tree.getDefaults()

Bac à sable et limites

Les scripts s'exécutent dans un interpréteur QuickJS isolé. Il n'y a ni DOM, ni window, ni document, ni minuteurs, ni accès au réseau. Un script qui a besoin de données extérieures prend une entrée de fichier.

Pendant l'exécution d'un script

LimiteValeur
Mémoire128 MB
Durée d'exécution10 minutes, puis l'exécution est interrompue
Taille de la source dans l'éditeur1 000 000 de caractères
Plage de coordonnées±30,000,000
Sortie du journal1 000 lignes, 2 000 caractères par ligne
Blocs placésIllimité

À la soumission

Le code soumis est de nouveau vérifié sur le serveur, et ces règles sont plus strictes que celles de l'éditeur.

  • Le code compilé doit faire 100 Ko ou moins. Un très gros script peut donc être exécuté localement mais pas publié.
  • Le code ne doit contenir aucun des éléments suivants : eval(, Function(, setTimeout, setInterval, XMLHttpRequest, fetch(, import(, require(, process., child_process, fs., globalThis, global., __proto__, constructor.constructor.
  • Un code identique est rejeté comme doublon : le serveur calcule une empreinte du script compilé, republier tel quel le travail de quelqu'un d'autre ne passera donc pas.

La vérification des motifs est une simple correspondance de texte

Il n'analyse pas votre code, il se déclenche donc aussi dans les commentaires et les chaînes, et une variable inoffensive nommée fetchRow sera rejetée parce qu'elle contient fetch(. Renommez-la et soumettez à nouveau.

Soumettre un script

Appuyez sur Enregistrer en étant connecté. On vous demandera un titre et une description, et le script entrera dans une file de validation.

  1. Un script en attente n'est visible que par vous. Sa page liste chaque version que vous avez soumise avec l'état de chacune.
  2. Une fois approuvé, le script apparaît dans le catalogue public avec sa propre page et sa propre adresse, et tout le monde peut l'exécuter.
  3. Enregistrer à nouveau crée une nouvelle version, validée séparément. La version approuvée reste en ligne en attendant, une modification ne casse donc jamais ce qu'utilisent les autres.
  4. Vous pouvez supprimer vos propres scripts à tout moment depuis la page du script.

Avant de soumettre

  • Donnez-lui un titre de 100 caractères maximum et une description d'au moins 10 caractères qui dit ce qu'il construit et à quoi servent les entrées.
  • Vérifiez qu'il s'exécute jusqu'au bout avec ses entrées par défaut. Un script qui ne fonctionne qu'avec un fichier précis est difficile à approuver.
  • Donnez à chaque entrée une valeur par défaut raisonnable, un libellé clair et une plage qui ne peut pas produire une construction trop grande pour être affichée.
  • Les titres et les descriptions passent par un filtre de contenu, et les liens d'une description sont comparés à une liste de blocage.

Le nom et la description sont figés

Une fois qu'un script existe, les enregistrements suivants modifient le code et créent une version. Ils ne le renomment pas : choisissez donc un titre que vous êtes content de garder.

Dépannage

Aucune fonction main définie

Le script a été analysé mais n'a jamais déclaré main. Déclarez-la comme fonction de premier niveau, pas imbriquée dans une autre ni assignée de façon conditionnelle.

Nom de bloc de script invalide

Un appel setBlock ou fillBox a reçu autre chose qu'une chaîne d'identifiant de bloc. Cela vient généralement d'une recherche qui peut échouer, comme un indice de palette qui a dépassé la fin d'un tableau.

Coordonnée de script invalide

Une coordonnée était NaN, infinie ou en dehors de ±30 000 000. Presque toujours une division par zéro ou une entrée convertie en NaN.

Le script s'exécute mais rien n'apparaît

Vérifiez que main renvoie { creation }, et que la création que vous renvoyez est bien celle dans laquelle vous avez placé les blocs.

Un bloc s'affiche comme un simple cube ou un simple poteau

Il a été placé sans états utilisables. Utilisez Textures.getPlacementStates, et Textures.getStateOptions pour les connexions des vitres, barrières et murets.

Autre chose ? Contactez-nous depuis la page FAQ.