🌀 Скриптинг

Соглашения

При создании скриптинга для 3DCoat использовались соглашения, знание которых значительно упростит тебе работу.

1. В скриптинге используется fluent-интерфейс. Т. е. можешь создавать цепочки методов.

   Builder b;
   Mesh m = b.sphere().radius( 7 ).details( 0.5 ).build();

2. Названия классов и методов описывают функциональность.
3. Функции создаём в рамках групп. Для этого заводим классы-синглетоны: Builder, UI, Coat, Debug и т.п..
4. Названия классов пишутся с прописной буквы.
5. Названия методов и функций пишутся со строчной буквы.
6. Символ подчёркивания ни в названиях классов, ни в названиях методов не используется. Работаем в camelCase-нотации.
7. Свойства класса - закрытые. Для работы с ними существуют одноимённые методы.
8. Геттеры и сеттеры реализованы без префикса get и set.
9. Количество всегда представлено типом int.
10. Методы, возвращающие количество, представлены как countНазваниеВоМнЧ().
11. Рядом с методами, возвращающими количество, есть методы вида hasНазваниеВоМнЧ().
12. Создаются дублирующие методы для более удобного кода в скрипте. Например, topRadius( a ) и bottomRadius( b ) эквивалентны методу radius( a, b ).
13. Некоторые методы способны "раскрыть" свои параметры. Например, вместо position( Vec3( 0, 120, 0 ) ) можешь писать positionTop( 0, 120, 0 ).
14. Подчинённые классы и перечисления "утоплены" в namespac'ы, но *не глубже*, чем на один уровень. Например, класс PolyMesh::FaceInfo содержит подчинённый enum UVEdgeMask. Элементы этого перечисления доступны из скриптов по префиксу PolyMesh::UVEdgeMask::.
15. Методы, регистрации классов, функций размещаются, по возможности, в алфавитном порядке.

Скрипт-движок 3DCoat был полностью переписан. Для обеспечения обратной совместимости, оставлены все методы из прошлого движка (см. файл ScriptInterface.h).

За основу оформления кода для *нового скриптинга* взят класс Mat3. Пожалуйста, используй этот класс как пример при создании своих классов.

Как создать свой класс

К делу!)

3DCoat работает с AngelScript. См. о нём на сайте и в секции Расширение скриптинга.

Построим класс Vec3 для работы с 3D-векторами в скриптах 3DCoat.

Для этого создадим в папке Scripto файл SVec3.h.

Warning

Всегда добавляй префикс S в названия файлов скриптинга: C++линковщик будет тебе благодарен.

namespace coat {
    namespace scripto {

class Vec3 {
public:
    typedef comms::cVec< float, 3 >  vec3_t;
    struct About {
        vec3_t  v;
    };

public:
    Vec3() : a( {} ) {}
    Vec3( const vec3_t& v ) : a( { v } ) {}
    Vec3( float xyz ) : a( { { xyz, xyz, xyz } } ) {}

private:
    const vec3_t& v() const { return a.v; }
    vec3_t& v() { return a.v; }

private:
    About  a;
};


class RegisterVec3 : public RegisterLikeNew< Vec3 > {
public:
    static void opConstructXYZ( float x, float y, float z, Vec3* in ) {
        new ( in )Vec3( Vec3::vec3_t( x, y, z ) );
    }
};

} } // coat scripto

Появление RegisterVec3 позволит сократить регистрацию нашего класса в C++коде (см. ниже).

Структура About - удобная обёртка к построению классов скриптинга. Она позволяет абстрагироваться от наследуемого C++кода, функционал которого мы планируем сделать доступным из скриптов.

Метод v() предоставляет доступ к элементу About::v. Добавлен в рамках "единого подхода".

Пространство имён coat::scripto также указано не просто так: оно обеспечит тебе и другим программистам Пилгвей гарантированную уникальность имён в проекте.

Регистрируются классы в файле Scripto.cpp.

Зарегистрируем Vec3:

// регистрируем тип
csRTypeCDA( Vec3, engine );
// регистрируем конструктор
csRConstr( Vec3, XYZ, (float, float, float), engine );

csRTypeCDA и csRConstr - это, конечно же, макросы.

Они очень помогают сократить код. Сомневаешься? Что ж, ты вправе вместо кода выше писать так:

// регистрируем тип
rtype(engine, "Vec3",
    sizeof( Vec3 ), asOBJ_VALUE | asOBJ_APP_CLASS_CDA);
rbeh(engine, "Vec3", asBEHAVE_CONSTRUCT,
    "void f()", asFUNCTION( RegisterVec3::opConstruct ));
rbeh(engine, "Vec3", asBEHAVE_DESTRUCT,
    "void f()", asFUNCTION( RegisterVec3::opDestruct ));
rmethod(engine, "Vec3",
    "className& opAssign(const className &in)",
    asFUNCTION( RegisterVec3::opAssign ));

// регистрируем конструктор
rbeh(engine, "Vec3", asBEHAVE_CONSTRUCT,
    "void f(float, float, float)",
    asFUNCTION( RegisterVec3::opConstructXYZ ));

Эти два варианта кода делают одно и то же. Это возможно благодаря соглашениям, о которых мы помним и которых придерживаемся при разработке *любого* класса скриптинга.

Полный список макросов для регистрации почти всех возможных методов и классов можешь найти в файле SMacros.h.

На этом с конструкторами можно и остановиться. Но, допустим, мы хотим сделать жизнь скрипт-программиста приятней. Для этого дадим ему ещё два дополнительных конструктора для нашего класса:

// инициализация трёх координат одним значением
csRConstr( Vec3, All, (float), engine );
// инициализация в виде списка в стиле C++11
csRListConstr( Vec3, Elements, "(int &in) { float, float, float }", engine );

а чтобы новые конструкторы работали, добавим в RegisterVec3 пару методов:

static void opConstructAll( float v, Vec3* in ) {
    opConstructXYZ( v, v, v, in );
}
static void opConstructXYZ( float x, float y, float z, Vec3* in ) {
    new ( in )Vec3( Vec3::vec3_t( x, y, z ) );
}
static void opListConstructElements( const float* l, Vec3* in ) {
    opConstructXYZ( l[ 0 ], l[ 1 ], l[ 2 ], in );
}

Добавим к вектору полезный функционал.

Возможность сравнения себя с другим вектором

bool operator==(const Vec3& b) const {
    return v() == b.v();
}

Геттеры и сеттеры для координат

Vec3& x( const float& value ) { v()[ 0 ] = value; return *this; }
float x() const { return v()[ 0 ]; }
Vec3& y( const float& value ) { v()[ 1 ] = value; return *this; }
float y() const { return v()[ 1 ]; }
Vec3& z( const float& value ) { v()[ 2 ] = value; return *this; }
float z() const { return v()[ 2 ]; }

Плюс допустимость работать с вектором как со списком

Vec3& operator()( int i, float value ) { v()[ i ] = value; return *this; }
float operator()( int i ) const { return v()[ i ]; }

Оператор для изменения знака хранимых вектором координат

Vec3 operator-() const { return Vec3( -v() ); }

и взятие модуля координат как самого вектора, так и дублируя его (см. Как создать свой класс).

Vec3& abs() { *this = absCopy(); return *this; }
Vec3  absCopy() const { return vec3_t::Abs( v() ); }

Также приятным дополнением человеку, который будет пользоваться твоим классом, окажется функция удержания значений в заданном диапазоне, в среде программистов известная как clamp

Vec3& clamp( float min, float max ) {
     this = clampCopy( min, max );
    return *this;
}
Vec3  clampCopy( float min, float max ) const {
    return vec3_t::Clamp( v(), min, max );
}
Vec3& clamp( const Vec3& min, const Vec3& max ) {
     this = clampCopy( min, max );
    return *this;
}
Vec3  clampCopy( const Vec3& min, const Vec3& max ) const {
    return vec3_t::Clamp( v(), min.v(), max.v() );
}

Конечно же, удобным арифметическим операциям он тоже будет рад

Vec3& operator+=( const Vec3& b )  { v() += b.v(); return *this; }
Vec3& operator-=( const Vec3& b )  { v() -= b.v(); return *this; }
Vec3& operator*=( const Vec3& b )  { v() *= b.v(); return *this; }
Vec3& operator*=( const float& k ) { v() *= k; return *this; }
Vec3& operator/=( const Vec3& b )  { v() /= b.v(); return *this; }
Vec3& operator/=( const float& k ) { v() /= k; return *this; }

Vec3 operator+( const Vec3& b ) const  { return Vec3( v() + b.v() ); }
Vec3 operator-( const Vec3& b ) const  { return Vec3( v() - b.v() ); }
Vec3 operator*( const Vec3& b ) const  { return Vec3( v() * b.v() ); }
Vec3 operator*( const float& k ) const { return Vec3( v() * k ); }
Vec3 operator/( const Vec3& b ) const  { return Vec3( v() / b.v() ); }
Vec3 operator/( const float& k ) const { return Vec3( v() / k ); }

Знание, нормализован ли наш вектор? Может, инициализирован нулями?

bool normalized() const { return v().IsNormalized(); }
bool zero() const { return v().IsZero(); }

и сама нормализация

Vec3& normalize() {
     this = normalizeCopy(); return *this;
}
Vec3  normalizeCopy() const {
    return vec3_t::Normalize( v() );
}

Округление до целого. Почему бы и нет?

Vec3& round() { *this = roundCopy(); return *this; }
Vec3  roundCopy() const { return vec3_t::Round( v() ); }

Пусть он также умеет считать угол, образуемый с другим вектором

float angle( const Vec3& b ) const {
    return vec3_t::Angle( v(), b.v() );
}

Расстояние до другого вектора, когда векторы используют как 3D-координаты

float distance( const Vec3& b ) const {
    return vec3_t::Distance( v(), b.v() );
}

Длина вектора

float length() const { return v().Length(); }

и квадрат длины для тех, кто умеет писать быстрый код

float lengthSquared() const { return v().LengthSq(); }

dot- и cross-операции (куда же без них в 3D-графике?) Причём, cross сделаем в двух видах: меняющий сам вектор и возвращающий копию вектора (см. Как создать свой класс).

float dot( const Vec3& b ) const { return vec3_t::Dot( v(), b.v() ); }
Vec3& cross( const Vec3& b ) { *this = crossCopy( b.v() ); return *this; }
Vec3  crossCopy( const Vec3& b ) const { return vec3_t::Cross( v(), b.v() ); }

Вспомним и об интерполяции

Vec3& lerp( const Vec3& b, float s ) {
     this = lerpCopy( b, s );
    return *this;
}
Vec3  lerpCopy( const Vec3& b, float s ) const {
    return vec3_t::Lerp( v(), b.v(), s );
}
Vec3& slerp( const Vec3& b, float s ) {
     this = slerpCopy( b, s );
    return *this;
}
Vec3  slerpCopy( const Vec3& b, float s ) const {
    return vec3_t::Slerp( v(), b.v(), s );
}

Наш вектор также будет иметь прединициализированные значения для создания эффективного кода

static const Vec3  ONE;
static const Vec3  UNDEFINED;
static const Vec3  ZERO;

и сумеет превращаться в строку

operator std::string() const;

Чтобы показать тебе больше, реализуем методы, которые возвращают объект Vec3, инициализированный случайным значением

static Vec3 rand( float min, float max ) {
    return rand( Vec3( min ), Vec3( max ) );
}
static Vec3 rand( const Vec3& min, const Vec3& max );

Остановимся на этом, осознав, что сейчас наша задача не создание навороченного 3D-вектора, а базовые принципы создания нового класса для скриптинга на AngelScript.

Для реализации желаемого выше функционала одним H-файлом не обойтись...

Вынесем реализацию некоторых декларированных выше методов в CPP-файл:

#include "stdafx.h"
#include "SVec3.h"
#include "helper/Funcs.h"

namespace coat {
    namespace scripto {

const Vec3  Vec3::ONE( 1 );
const Vec3  Vec3::UNDEFINED( {
    make::undefined< float >(),
    make::undefined< float >(),
    make::undefined< float >() } );
const Vec3  Vec3::ZERO( 0 );

Vec3 Vec3::rand( const Vec3& min, const Vec3& max ) {
    return Vec3( {
        comms::cMath::Rand( min.x(), max.x() ),
        comms::cMath::Rand( min.y(), max.y() ),
        comms::cMath::Rand( min.z(), max.z() )
    } );
}

Vec3::operator std::string() const {
    // просто, но не оптимально
    std::ostringstream  ss;
    ss << v();
    return ss.str();
}

} } // coat scripto

Помнишь, вначале мы регистрировали конструкторы Vec3 в файле Scripto.cpp? Возвращаемся к нему и дописываем:

csRValueOf_( Vec3, rand, (float, float), engine );
csRValueOf( Vec3, rand, (const Vec3 &in, const Vec3 &in), (const Vec3&, const Vec3&), engine );
csRImplConv( Vec3, string, engine );
csREquals( Vec3, engine );
csRG_( Vec3, normalized, bool, engine );
csRG_( Vec3, zero, bool, engine );
csRSIndexFunctor_( Vec3, (int, float), engine );
csRGIndexFunctor_( Vec3, (int) const, float, engine );
csRSG_( Vec3, x, float, engine );
csRSG_( Vec3, y, float, engine );
csRSG_( Vec3, z, float, engine );
csRNeg( Vec3, engine );
csRAddAssignSame( Vec3, engine );
csRSubAssignSame( Vec3, engine );
csRMulAssignSame( Vec3, engine );
csRMulAssign_( Vec3, float, engine );
csRDivAssignSame( Vec3, engine );
csRDivAssign_( Vec3, float, engine );
csRAddSame( Vec3, engine );
csRSubSame( Vec3, engine );
csRMulSame( Vec3, engine );
csRMul_( Vec3, float, engine );
csRMulR_( Vec3, float, engine );
csRDivSame( Vec3, engine );
csRDiv_( Vec3, float, engine );
csRPOther__( Vec3, float, angle, (const Vec3 &in) const, engine );
csRPOther__( Vec3, float, distance, (const Vec3 &in) const, engine );
csRPOther__( Vec3, float, dot, (const Vec3 &in) const, engine );
csRG_( Vec3, length, float, engine );
csRG_( Vec3, lengthSquared, float, engine );
csRMPAndCopy_( Vec3, abs, (), engine );
csRMPAndCopy_( Vec3, clamp, (float, float), engine );
csRPAndCopy_( Vec3, Vec3, clamp, (const Vec3 &in, const Vec3 &in), (const Vec3&, const Vec3&), engine );
csRMPAndCopy_( Vec3, cross, (const Vec3 &in), engine );
csRPAndCopy__( Vec3, Vec3, lerp, (const Vec3 &in, float), engine );
csRMPAndCopy_( Vec3, normalize, (), engine );
csRMPAndCopy_( Vec3, round, (), engine );
csRPAndCopy__( Vec3, Vec3, slerp, (const Vec3 &in, float), engine );

Реальный класс Vec3 содержит немного больше добавленных здесь возможностей, но разве тебе для понимания как добавить свой класс в скриптинг 3DCoat этого недостаточно?

Посмотрим, как можем использовать созданный нами выше класс в 3DCoat.

Vec3  a( 10, 30, 90 );
Vec3  b = { 11, 33, 99 };
Vec3  plus = a + b;
Vec3  minus = a - b;
if (a == b) {
    ...
}
float  theta = a.angle( b );
Vec3  randomA = Vec3::rand(
    Vec3( -30, -20, -10 ),
    Vec3( 70, 80, 90 ) );
Vec3  randomB = Vec3::rand( -30, 90 );
float  distance = a.distance( b );
float  length = a.length();
float  lengthSq = a.lengthSquared();
string s = (string) a;
...

Как создать свою функцию

В рамках принятых соглашений не рекомендуется создавать функции *без* класса (так называемые "глобальные функции").

Перед тем, как делать это, подумай, может ли желаемая тобой функция стать частью уже созданных классов?

• Builder - здесь собраны "строители" примитивов 3DCoat.
• Debug - все функции для визуальной и текстовой отладки.
• Safety - получение информации об ошибках при выполнении твоего скрипта.
• UI - всё, что связано с интерфейсом пользователя 3DCoat.
• Coat - всё, что может быть полезно при написании скриптов, но не может быть включено ни в один из представленных выше классов.

Но если свою задуманную функцию в уже созданных классах не видишь, рассмотрим пример связывания твоей функции с C++кодом.

Например, добавим глобальную функцию, которая делает активной указанную комнату 3DCoat.

Для этого декларируем функцию в файле ScriptInterface.h. Для простоты реализацию здесь указывать не будем.

void toRoom( const std::string& codeName ) {
    // Наша функция принимает в качестве параметра название комнаты
    // и, если такая комната существует, переключает 3DCoat на неё.
}

В RegisterScriptFunctions() дописываем строку

regf( engine, "void toRoom( string &in )", toRoom );

3DCoat гарантирует, что RegisterScriptFunctions() будет вызвана до использования нашей функции toRoom(), поэтому можем быть уверены, что код

toRoom( "Sculpt" );

переключит нас в Скульпт-комнату.

Впрочем, этого же ты мог достичь, изучив документацию по скриптингу, и обнаружив, что для переключения в Скульпт-комнату работает такой AngelScript-код:

SculptRoom room;

Изучай документацию, используй код повторно, пиши свой код так, чтобы другие могли им пользоваться. Одним из признаков хорошего кода является то, что им легко пользоваться *правильно* и сложно - *не правильно*.

Где живут примеры

В век Интернета почти каждый, кто изучает новый язык программирования, ищет, в первую очередь, примеры использования. А кто-то жаждет сразу найти решение **своей** задачи) И, возможно, решение уже есть!

Примеры и описание функций-классов скриптинга живут по этой ссылке.

Расширение скриптинга

Меня попросили написать этот раздел, но, признаюсь, я не понимаю зачем.

Ты работаешь программистом C++, почитал о принятых соглашениях, знаешь, как создать свой класс, свою функцию и сделать их доступными для скриптов 3DCoat. Значит, понимаешь, что основная работа уже проделана и для "расширения функционала" можно следовать такой стратегии:

1. Узнаёшь, что от тебя хотят.
2. Ищешь уже реализованный класс и берёшь его за основу.
3. Копируешь, меняешь, проверяешь - получаешь результат.

Когда посмотришь синтаксис AngelScript, увидишь, что он большей частью повторяет синтаксис C++. Почитав и поигравшись с кодом, убедишься и в том, что эти скрипты выполняются очень, очень быстро (скажу по секрету: основная причина - строгая типизация).

Но можно пойти дальше и помочь развитию AngelScript, включившись в работу над скрипт-движком вместе с Andreas Jonsson. Andreas - один из программистов, который идёт в ногу со временем. Например, AngelScript реализовал у себя списки инициализации как только они были озвучены в стандарте C++11. И корутины, которые столько лет ждут сишники, добавлены в AngelScript давным-давно.

Есть много задач, которые ещё предстоит решить в этом скрипт-движке.

Присоединяйся!) Это интересно и полезно.

Также, здорово будет хотя бы раз в год читать, что нового появилось в AngelScript и обновлять его библиотеку в 3DCoat. Помимо новых возможностей, исправленных ошибок, ты, как правило, получаешь лучшую производительность. Последнее обновление AngelScript принесло 3DCoat'у ускорение скрипт-кода более чем в 3 раза!

Да, при желании, ничто не мешает расширить 3DCoat и другими скрипт-движками. Тем же Python, JavaScript и неоправданно громким Lua. Для этого:

1. Найди соответствующие C++библиотеки (на сегодня их хватает).
2. Убедись, что лицензия допускает их использование в коммерческом проекте.
3. Свяжи доступные в AngelScript классы и методы с новыми движками. Лучше не переписывать "под копирку" классы, созданные под AngelScript, а *завязать* на них новые классы, пробрасывая к ним функциональность, которую хочешь видеть на других скрипт-движках.
4. Перепиши код, созданный для AngelScript, используя синтаксис другого скрипт-движка.
5. Протестируй работу нового кода.

Когда тебе скажут сделать подобное, спроси себя и заказчика: "Кто всё это будет поддерживать после?"

Успехов!