Перейти к основному содержанию

Аннотация блоков для языка Catnip

7 июня 2024 г.

Аннотация блоков для языка Catnip

Автоматически переведённая страница

К сожалению, на полный ручной перевод у нас не хватает ресурсов.
Если вы увидели ошибку — отправьте пул-риквест с исправлениями (ссылка для редактирования в конце страницы).

Ct.js проверяет два типа файлов при добавлении блоков для вашего catmod:

Обе записи необязательны. Вы можете использовать одну или обе, чтобы создать блоки для Catnip.

Все обнаруженные блоки будут помещены в категорию, специальную для вашего catmod, но некоторые блоки могут быть дополнительно добавлены в встроенные категории по имени (поддерживается только в файле blocks.js на данный момент).

Добавление аннотаций @catnip в файл types.d.ts

Вы можете добавить несколько аннотаций @catnip, чтобы помочь ct.js лучше преобразовать ваш файл объявлений в пригодные для использования блоки catnip. Они добавляются как специальные теги в комментарии JSDoc. Например:

/**
 * Создает новую копию заданной шаблонной карты внутри конкретной комнаты.
 * @param template Имя используемой шаблонной карты.
 * @catnipAsset template:template
 * @param [x] X-координата новой копии. По умолчанию 0.
 * @param [y] Y-координата новой копии. По умолчанию 0.
 * @param [room] Комната, в которую добавляется копия.
 * По умолчанию текущая комната.
 * @param [params] Необязательный объект, параметры которого будут применены
 * к копии перед событием OnCreate.
 * @returns Созданную копию.
 * @catnipSaveReturn
 */
function copyIntoRoom(template: string, x = 0, y = 0, room?: Room, params?: Record<string, unknown>): BasicCopy;

Свойства автоматически преобразуются в блоки вычислений. (Тот, что в форме колбасы.) По умолчанию функции, которые не возвращают значения, преобразуются в блоки команд (в прямоугольной форме), а те, которые возвращают значения, преобразуются в блоки вычислений. Однако вы можете изменить это поведение — см. ниже.

Ct.js распознает следующие теги:

Добавление блоков через файл blocks.js

Файл blocks.js должен быть модулем CommonJS (то есть он должен возвращать значение с помощью module.exports). Файл должен возвращать массив блоков, которые вы хотите добавить в библиотеку Catnip.

Вот пример файла blocks.js из catmod "place":

module.exports = [
    {
        name: 'Переместить эту копию по линии, останавливаясь перед',
        name_Ru: 'Переместить эту копию по линии, останавливаясь перед',
        type: 'command',
        code: 'move template bullet',
        icon: 'move',
        category: 'Movement',
        pieces: [
            {
                type: 'argument',
                key: 'cgroup',
                typeHint: 'string',
                required: true
            },
            {
                type: 'filler'
            },
            {
                type: 'label',
                name: 'store in',
                i18nKey: 'store in'
            },
            {
                type: 'argument',
                key: 'return',
                typeHint: 'wildcard'
            }
        ],
        jsTemplate: (values) => {
            if (values.return !== 'undefined') {
                return `${values.return} = this.moveBullet(${values.cgroup}, ${values.precision || 1});`;
            }
            return `this.moveBullet(${values.cgroup}, ${values.precision || 1});`;
        }
    },
    {
        name: 'Переместить эту копию, останавливаясь перед',
        name_Ru: 'Переместить эту копию, останавливаясь перед',
        type: 'command',
        code: 'move template smart',
        icon: 'move',
        category: 'Movement',
        pieces: [
            {
                type: 'argument',
                key: 'cgroup',
                typeHint: 'string',
                required: true
            },
            {
                type: 'filler'
            },
            {
                type: 'label',
                name: 'store in',
                i18nKey: 'store in'
            },
            {
                type: 'argument',
                key: 'return',
                typeHint: 'wildcard'
            }
        ],
        jsTemplate: (values) => {
            if (values.return !== 'undefined') {
                return `${values.return} = this.moveSmart(${values.cgroup}, ${values.precision || 1});`;
            }
            return `this.moveSmart(${values.cgroup}, ${values.precision || 1});`;
        }
    }
];

Поля name, type, code, jsTemplate и pieces являются обязательными.

Любые обнаруженные ошибки будут записаны в консоль разработчика ct.IDE (доступную из головного меню — Отладка), когда вы откроете проект или включите новый catmod.

Перевод блоков

Вам может быть mogelijk повторно использовать уже использованные ключи. Доступные переводческие ключи можно найти в файле data — i18n — English.json в папке ct.js — объект catnip.

Если вы не можете повторно использовать существующие ключи, вы можете добавить переводы для name и displayName, добавив подобный ключ с подчеркиванием и кодом региона: например, name_Ru будет именем, используемым для русского языка.

Увеличение встроенных категорий

Вы можете добавить поле category для блока и указать имя категории, в которую вы хотите добавить этот блок.

Имена встроенных категорий:

Добавление дополнительных элементов (иконки, аргументов) в блок

Все, что не является иконкой или названием блока, определяется в массиве pieces блока. Каждый элемент может быть одним из следующих интерфейсов:

declare interface IBlockPieceLabel {
    type: 'label';
    name: string;
    i18nKey?: string;
}
declare interface IBlockPieceIcon {
    type: 'icon';
    icon: string;
}
declare interface IBlockPieceCode {
    type: 'code';
    key: string;
}
declare interface IBlockPieceArgument { // Чип для константного значения или ссылки на ресурс
    type: 'argument';
    key: string;
    typeHint: blockArgumentType;
    defaultConstant?: string;
    required?: boolean;
    assets?: resourceType | 'action';
}
declare interface IBlockPieceTextbox {
    type: 'textbox';
    key: string;
    default?: string;
}
declare interface IBlockPieceBlocks { // Область блока
    type: 'blocks';
    placeholder?: 'ничто не делать';
    key: string;
}
declare interface IBlockPieceBreak { // Полосчатая линия
    type: 'break'
}
declare interface IBlockFiller { // Перемещает следующие блоки вправо
    type: 'filler'
}
declare interface IBlockAsyncMarker { // Добавляет иконку Async
    type: 'asyncMarker'
}

blockArgumentType может быть 'boolean' | 'number' | 'string' | 'wildcard' | 'void', но 'void' зарезервировано для внутреннего использования и не должно использоваться в пользовательских блоках.

Вывод кода JavaScript

Каждый блок должен иметь поле jsTemplate, которое должно быть функцией. Эта шаблонная функция передается с аргументом values, который позволяет читать все аргументы и предварительно скомпилированный код списков блоков. Не нужно экранировать или кавычками оборачивать строки — используйте их так, как они есть, поскольку компилятор уже делает это для вас.

Блоки должны возвращать строку, содержащую действительный сценарий JavaScript или выражение.

Когда аргумент пуст, если не задано defaultConstant, то аргумент устанавливается в "undefined". Обратите внимание, что это строка. Если список блоков пуст, его значение — пустая строка. ("")

Установка иконки для блока категории

В файл module.json можно добавить поле "icon" в раздел main и установить его на строку — имя одной из иконок, перечисленных в главном меню ct.js — Метаданные — Список иконок.

Your primary language is en-US, do you want to switch to it?

Ваш основной язык - en-US, вы хотите переключиться на него?