Установка через npm и подключение через CDN

Oimo.js — это JavaScript-библиотека для расчёта трёхмерной физики твёрдых тел, ориентированная на работу в браузере и интеграцию с WebGL-движками (например, Three.js). Установка через npm применяется в проектах с использованием сборщиков модулей (Vite, Webpack, Rollup, Parcel) и в Node.js-среде.

1. Инициализация проекта

Если проект ещё не создан, выполняется инициализация:

npm init -y

Создаётся файл package.json, в котором будут храниться зависимости и параметры проекта.

2. Установка библиотеки

Добавление Oimo.js выполняется командой:

npm install oimo

После установки пакет появляется в разделе dependencies файла package.json, а исходный код библиотеки — в каталоге node_modules.

Пример фрагмента package.json:

{
  "dependencies": {
    "oimo": "^1.0.9"
  }
}

3. Импорт в ES-модулях

При использовании современного JavaScript (ES Modules) импорт выполняется следующим образом:

import * as OIMO from 'oimo';

Либо, если требуется конкретный экспорт:

import OIMO from 'oimo';

Форма импорта зависит от версии пакета и способа его сборки. В большинстве случаев используется пространство имён OIMO.

4. Пример базовой инициализации мира

После импорта создаётся физический мир:

import * as OIMO from 'oimo';

const world = new OIMO.World({
    gravity: [0, -9.8, 0]
});

Параметры конструктора:

gravity — вектор гравитации
timestep — шаг симуляции
iterations — количество итераций решения ограничений
broadphase — алгоритм широкофазной проверки столкновений

5. Использование со сборщиками

Vite

В main.js:

import * as OIMO from 'oimo';

Vite автоматически обрабатывает зависимость без дополнительной конфигурации.

Webpack

Webpack корректно обрабатывает пакет из node_modules. Дополнительных настроек, как правило, не требуется.

При необходимости можно добавить оптимизацию:

resolve: {
    extensions: ['.js']
}

6. Работа в TypeScript

Если проект использует TypeScript, возможны два варианта:

Использование встроенных типов (если они присутствуют в пакете).
Подключение деклараций вручную.

Импорт остаётся стандартным:

import * as OIMO from 'oimo';

При отсутствии типов создаётся файл oimo.d.ts:

declare module 'oimo';

Подключение Oimo.js через CDN

CDN-подключение используется в простых HTML-проектах без сборщика.

1. Подключение через тег `<script>`

Пример использования публичного CDN:

<script src="https://cdn.jsdelivr.net/npm/oimo@1.0.9/build/oimo.min.js"></script>

После загрузки библиотеки глобальный объект OIMO становится доступным в пространстве окна (window.OIMO).

2. Базовая инициализация

<script>
    const world = new OIMO.World({
        gravity: [0, -9.8, 0]
    });

    console.log(world);
</script>

В этом режиме модульная система не используется — библиотека подключается как глобальный скрипт.

3. Использование ES-модулей через CDN

Современные CDN поддерживают импорт как ES-модуля:

<script type="module">
    import * as OIMO from 'https://cdn.jsdelivr.net/npm/oimo@1.0.9/build/oimo.module.js';

    const world = new OIMO.World({
        gravity: [0, -9.8, 0]
    });

    console.log(world);
</script>

Преимущества такого подхода:

отсутствие глобальных переменных;
поддержка import/export;
возможность использования вместе с другими модульными библиотеками.

4. Выбор версии

В URL можно фиксировать версию:

https://cdn.jsdelivr.net/npm/oimo@1.0.9/...

Либо использовать последнюю доступную:

https://cdn.jsdelivr.net/npm/oimo/...

Фиксация версии предпочтительна в продакшн-проектах для предотвращения несовместимостей.

Сравнение npm и CDN-подключения

Характеристика	npm	CDN
Использование сборщика	Да	Нет (опционально)
Управление версиями	Через package.json	Через URL
Подходит для крупных проектов	Да	Ограниченно
Работа офлайн	Да	Нет
Глобальные переменные	Нет	Да (при обычном script)

Когда используется npm

проекты на React, Vue, Svelte;
использование Three.js вместе с физикой;
необходимость строгого контроля зависимостей;
серверный рендеринг или Node.js.

Когда используется CDN

учебные примеры;
прототипирование;
простые HTML-страницы без сборки;
демонстрационные стенды.

Структура файлов при npm-установке

После установки каталог библиотеки обычно содержит:

node_modules/oimo/
├── build/
│   ├── oimo.js
│   ├── oimo.min.js
│   └── oimo.module.js
├── src/
└── package.json

oimo.js — обычная версия
oimo.min.js — минифицированная
oimo.module.js — ES-модуль

При использовании сборщика чаще применяется модульная версия.

Проверка корректности подключения

Для npm

import * as OIMO from 'oimo';

console.log(OIMO);

Если объект содержит классы World, RigidBody, Shape, подключение выполнено корректно.

Для CDN

<script>
    console.log(typeof OIMO);
</script>

Значение "object" свидетельствует об успешной загрузке.

Частые ошибки

Ошибка: `OIMO is not defined`

Причины:

скрипт подключён после основного кода;
отсутствует тег <script>;
неверный путь к CDN.

Решение — переместить подключение библиотеки выше пользовательского кода или использовать type="module".

Ошибка импорта в npm

Cannot find module 'oimo'