Устройство

device — то, что приложение знает о телефоне или компьютере, на котором работает: платформа, язык пользователя, размер экрана, сеть, хаптика и датчик движения — обычный глобальный объект. Локализация строится на device.language; модуля переводов в SDK нет.

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

Платформы: все хосты; хаптика и датчик движения — только на iOS и Android (в вебе — одно простое жужжание, без движения), HDR-картинка — только на десктопе под macOS (экран XDR) — проверяй device.motion.available / device.hdr.available.

Обзор

TypeScript
const info = UIText('').named('info')
const show = () => {
  info.text = `${device.platform}, ${device.language}, ${device.width} × ${device.height}, ${device.online ? 'online' : 'offline'}`
}
show()                                     // любое значение читается в любой момент
device.addEventListener('resize', show)    // поворот или ресайз окна (логические px)
device.addEventListener('offline', show)
device.addEventListener('online', show)

const buzz = UIButton(UIText('Buzz')).named('buzz').onClick(() => device.vibrate('light'))
UIScreen(UIColumn(info, buzz)).open()

Телефон, десктоп или веб: device.platform

Проверь, где работает приложение — на телефоне, на десктопе или в браузере, — чтобы выбрать управление: device.platform называет модель ввода, а не ОС.

TypeScript
device.platform     // "ios" | "android" | "desktop" | "web" (только чтение)

Windows, macOS и Linux все сообщают "desktop". Браузер сообщает "web" — и браузер телефона, и браузер компьютера, поэтому веб-сборка предлагает оба вида управления, — и так же headless-тесты (lecodes render / lecodes test).

TypeScript
const hint =
  device.platform === 'ios' || device.platform === 'android' ? 'Drag the stick to move'
  : device.platform === 'desktop' ? 'W A S D to move, the mouse to look'
  : 'Drag the stick, or use W A S D'          // "web": браузер телефона или компьютера
UIScreen(UIText(hint).named('hint')).open()

Локализация

Язык пользователя: device.language

device.language — язык пользователя: код в нижнем регистре без региона — "en", "de", "ru", "zh", — ключ, по которому выбираются тексты и форматы приложения. Он читается у хоста при каждом обращении; события об изменении нет.

TypeScript
device.language     // "en", "de", "ru", "zh" … (только чтение)
Хост device.language
iOS первый предпочитаемый язык пользователя, обрезанный до двух букв
Android локаль приложения, как её сообщает Android (Locale.language), без обрезки: бывает "iw" для иврита и "in" для индонезийского (в остальных местах — "he" / "id") или из трёх букв ("fil")
веб, веб-плеер язык браузера, обрезанный до двух букв; веб-плеер также принимает ?lang= в своём URL
десктоп (Windows, macOS, Linux), headless-тесты всегда "en"
Note

региона и письменности нет: британский и американский английский оба читаются как "en", упрощённый и традиционный китайский — оба как "zh". Headless-тесты всегда идут на "en" — остальные языки проверяй через собственный переключатель языка приложения (ниже).

Перевод текстов приложения

Чтобы перевести тексты приложения на несколько языков, держи таблицу строк на каждый язык и выбирай её по device.language, с английским как запасным — модуля переводов в SDK нет, это паттерн. Сохраняемый сигнал помнит выбор языка пользователем между запусками.

TypeScript
const STRINGS: Record<string, Record<string, string>> = {
  en: { greeting: 'Hello!', switch: 'Русский' },
  ru: { greeting: 'Привет!', switch: 'English' },
}
const OLD_CODES: Record<string, string> = { iw: 'he', in: 'id' }   // коды Android для иврита и индонезийского
const deviceLang = OLD_CODES[device.language] ?? device.language

// язык устройства, пока пользователь не выбрал свой; выбор хранится на устройстве
const lang = signal(STRINGS[deviceLang] ? deviceLang : 'en').stored('lang')
const t = (key: string) => STRINGS[lang.value]?.[key] ?? STRINGS.en[key] ?? key

UIScreen(
  UIColumn(
    UIText(() => t('greeting')),
    UIButton(UIText(() => t('switch'))).named('language')
      .onClick(() => { lang.value = lang.value === 'ru' ? 'en' : 'ru' }),
  ),
).open()

t(key) откатывается к английскому для языка или ключа, которых нет в таблице, а UIText(() => t('greeting')) перерисовывается при смене lang. Тот же lang.value передавай в форматы чисел и дат.

Note

не убирай стрелку: UIText(t('greeting')) читает текст один раз и больше не обновляется — компилятор делает привязку только из прямого чтения .value сигнала (сигналы).

Числа и цены в формате локали

Числа и цены с валютой форматируй под локаль пользователя своим кодом: форматтера чисел и валют в SDK нет, а Intl не существует на Android, Windows и Linux — там toLocaleString('de-DE') печатает голые цифры (1234567.5), а new Intl.NumberFormat() бросает исключение. На iOS, macOS, в браузерах и headless-тестах Intl есть, так что тест разницы не покажет.

TypeScript
const SEPARATORS: Record<string, [group: string, decimal: string]> = {
  en: [',', '.'], de: ['.', ','], ru: ['\u00a0', ','],
}
const formatNumber = (n: number, decimals: number, lang: string): string => {
  const fixed = Math.abs(n).toFixed(decimals)            // "1234567.50" — чистый JS, любой хост
  const [whole, frac] = fixed.split('.')
  const [group, decimal] = SEPARATORS[lang] ?? SEPARATORS.en
  const sign = n < 0 && +fixed !== 0 ? '-' : ''
  return sign + whole.replace(/\B(?=(\d{3})+(?!\d))/g, group) + (frac ? decimal + frac : '')
}
const formatPrice = (amount: number, symbol: string, lang: string) =>
  lang === 'en' ? symbol + formatNumber(amount, 2, lang) : `${formatNumber(amount, 2, lang)} ${symbol}`

console.log(formatPrice(1234567.5, '€', 'en'))   // €1,234,567.50
console.log(formatPrice(1234567.5, '€', 'de'))   // 1.234.567,50 €
console.log(formatPrice(-9.99, '₽', 'ru'))       // -9,99 ₽

Даты на языке пользователя

Даты на языке пользователя показывай через date().format() и timeAgo() (Даты): они говорят только по-английски и по-русски — без локали следуют device.language, а любой другой язык получает английские названия месяцев. Передавай собственный язык приложения и держи паттерн на каждый язык — цифры там, где у date() нет названий месяцев:

TypeScript
const PATTERNS: Record<string, string> = { en: 'MMM D, YYYY', ru: 'D MMMM YYYY', de: 'DD.MM.YYYY' }
const formatDate = (when: number, lang: string) =>
  date(when).format(PATTERNS[lang] ?? PATTERNS.en, lang === 'ru' ? 'ru' : 'en')

const day = new Date(2026, 6, 10).getTime()
console.log(formatDate(day, 'en'))   // Jul 10, 2026
console.log(formatDate(day, 'ru'))   // 10 июля 2026
console.log(formatDate(day, 'de'))   // 10.07.2026 — цифры: у date() нет немецких названий месяцев
Note

неделя начинается с воскресенья (startOf('week')), и любая дата — в локальном времени устройства; API часовых поясов нет.

Языки с письмом справа налево

Арабский, иврит, персидский и урду читаются справа налево, но раскладка всегда идёт слева направо: строка ставит первого потомка слева на любом хосте. Отзеркаливай экран для этих языков сам — разверни потомков строки и выровняй её тексты вправо:

TypeScript
const rtl = ['ar', 'he', 'iw', 'fa', 'ur'].includes(device.language)   // арабский, иврит, персидский, урду

const avatar = UIBox().style({ width: 40, height: 40, borderRadius: 20, backgroundColor: '#4f7cff' })
const name = UIText('Dana Levi').style({ flex: 1, textAlign: rtl ? 'right' : 'left' })
UIScreen(
  UIRow(rtl ? [name, avatar] : [avatar, name]).style({ gap: 12, alignItems: 'center' }),   // отзеркалено вручную
).open()

flexDirection: 'row-reverse' (и 'column-reverse') отзеркаливает потомков контейнера, не меняя их порядка.

Note

iOS, Android и браузеры шейпят арабский текст и иврит и упорядочивают их внутри строки; десктоп (Windows, macOS, Linux) рисует их без шейпинга, буква за буквой слева направо — проверяй текст справа налево на телефоне.

Размер экрана и поворот: device.width, device.height, resize

Раскладывай приложение под экран, который у него есть: device.width × device.height — дисплей в логических px, а событие resize сообщает новый размер после поворота или ресайза окна.

TypeScript
device.width        // логические px (только чтение)
device.height       // логические px (только чтение)
device.addEventListener('resize', (width, height) => { })   // логические px
device.removeEventListener('resize', callback)              // та же ссылка на функцию

Оба — логические px (как clientX / clientY), никогда не физические пиксели. resize срабатывает при каждом изменении; придёт ли ещё одно на старте, зависит от хоста (headless-тесты и безоконный сервер его присылают), поэтому Обзор читает размер один раз и ещё раз в resize.

Note

оба могут читаться как 0, пока хост не сообщил размер — телефон может выполнить код приложения до первой раскладки, поэтому размер читается снова в resize. Headless-тесты сразу сообщают 390 × 844 (--width / --height его меняют).

Чтобы перестилизовать экран в ландшафте, классу стилей $landscape код не нужен (классы); чтобы зафиксировать ориентацию, используй app.setOrientation (app).

Плотность пикселей: device.pixelRatio

TypeScript
device.pixelRatio   // физических px на логический px: 1 на обычных дисплеях, 2–3 на телефонах (только чтение)

Рисуй Canvas с плотностью экрана, чтобы он оставался чётким: new Canvas(w, h, { pixelRatio: device.pixelRatio }). Телефоны сообщают масштаб экрана, десктоп — UI-масштаб своего окна, веб — devicePixelRatio браузера; в headless-тестах читается 1.

Связность: device.online и события online / offline

Покажи баннер, когда устройство ушло в офлайн, и синхронизируйся снова, когда сеть вернулась: device.online — текущее состояние, а события offline / online сообщают о каждом изменении.

TypeScript
const network = signal(device.online)
device.addEventListener('offline', () => { network.value = false })
device.addEventListener('online', () => { network.value = true })

const banner = UIText('No connection — changes will be sent later').named('offline')
  .style({ display: () => (network.value ? 'none' : 'flex'), backgroundColor: '#b3261e', color: '#ffffff', padding: 8 })
UIScreen(UIColumn(banner, UIText('Inbox'))).open()

device.online — подсказка по мере возможностей (семантика navigator.onLine): false — только когда платформа уверена, что сети нет; true не гарантирует, что интернет доступен, — всё равно обрабатывай ошибки fetch. Достаёт ли приложение до своего бэкенда (*.server.ts) — другой сигнал, глобал online: мнение транспорта, которое поддерживают его вызовы и его сокет.

Note

iOS, Android, десктоп и веб сообщают об изменениях (десктоп проверяет каждые 2 с). Headless-тесты и безоконный сервер читают true и никогда не шлют событий.

Точный тач для рисования: device.setPreciseTouch

TypeScript
device.setPreciseTouch(enabled: boolean)    // выключен по умолчанию

Более гладкие штрихи для рисования в 2D-сцене: с включённым точным тачем быстрый штрих доходит до событий указателя сцены на полной частоте сенсорного экрана (объединённые касания iOS, ≈120–240 Гц), а не раз в кадр дисплея (~60 Гц). Для UI из тапов и кнопок оставь его выключенным.

Note

только iOS и только для событий указателя 2D-сцены (Scene2D) — касания UI и 3D не меняются. Тихий no-op на Android, десктопе и в вебе.

Хаптика

Дай тактильный отклик, когда нажата кнопка, изменилось значение или действие удалось: device.vibrate(style) выдаёт один короткий хаптик семантического стиля (по умолчанию "medium").

TypeScript
const status = UIText('')
const like = UIButton(UIText('Like')).named('like')
  .onClick(() => device.vibrate('light'))                                   // лёгкий тап под пальцем
const save = UIButton(UIText('Save')).named('save')
  .onClick(() => { device.vibrate('success'); status.text = 'Saved' })   // исход: короткий паттерн «готово»
UIScreen(UIColumn(like, save, status)).open()
Группа Стили Смысл
Impact "light" "medium" "heavy" "soft" "rigid" "thud" физический «тап» разного веса; soft — глухой и мягкий, thud — глухой и сильный
Notification "success" "warning" "error" сигнал об исходе
Selection "selection" лёгкий тик для меняющегося значения (колесо пикера, шаги слайдера)
Device "tick" собственный короткий тап устройства: EFFECT_TICK на Android, удар rigid на iOS

Стили семантические, а не длительность, намеренно: именно этот словарь ощущается нативно и на iOS (UIFeedbackGenerator), и на Android (системные действия тактильного отклика) — у iOS нет публичного API для вибрации произвольной длины.

На Android эффект за каждым стилем — от производителя телефона: light / medium / heavy — это системные действия клавиш и кликов, поэтому они ощущаются как весь остальной телефон, а насколько различается их сила, зависит от модели. Сильнее всех различается tick — на одном телефоне это слабый тик, на другом резкий щелчок; бери его, когда нужен именно этот нативный тап, а не сила.

Note

iOS и Android. Веб даёт каждому стилю одно и то же короткое жужжание — там, где браузер вообще умеет вибрировать; десктоп и headless-тесты ничего не делают. Устройство без вибромотора (iPad) молчит, а системная настройка хаптики пользователя соблюдается. Вибрация геймпада — в Input.

Движение

Наклоняй телефон, чтобы рулить, или поворачивай, чтобы осматриваться: device.motion — датчик движения, объединяющий гироскоп и акселерометр. Запусти его, затем читай gravity (наклон) или attitude (ориентацию телефона) каждый кадр в update системы.

Note

только iOS и Android. На десктопе, в вебе и в headless-тестах available — false, start() резолвится в false, gravity читается как (0, 0, 0), а attitude — как Quat.identity: дай этим хостам управление касанием или клавиатурой.

TypeScript
class TiltSteer extends System<'tiltSteer'> {
  private car!: Mesh
  onAttach() {
    this.car = Mesh.box({ material: Material.lit({ color: '#e33' }), position: [0, 0.5, -4] })
    this.scene.add(Light.sun(), this.car)
  }
  update(dt: number) {
    this.car.x += device.motion.gravity.x * 4 * dt   // gravity.x: -1 — наклон влево … 1 — наклон вправо
  }
}
new Scene().system(TiltSteer).open()
device.motion.start().then((ok) => { if (!ok) toast('Tilt steering needs a phone') })

Камера кругового обзора (magic window, панорама) берёт ориентацию телефона:

TypeScript
class Panorama extends System<'panorama'> {
  update() { this.scene.camera.quaternion = device.motion.attitude }   // камера 360°, одна строка
}
const scene = new Scene().system(Panorama)
scene.open()

device.motion.start().then((ok) => { if (!ok) toast('No motion sensor') })   // начать обновления (батарея)
TypeScript
device.motion.recenter()             // сделать «здесь» направлением вперёд (только yaw)
device.motion.stop()                 // освободить сенсор
Член Тип Примечания
start(options?) Promise<boolean> Начать обновления. false = нет сенсора / в разрешении отказано.
stop() void Остановить обновления, освободить сенсор.
recenter() void Обнулить текущее направление (pitch/roll остаются привязаны к гравитации). No-op во фрейме "device".
available boolean Есть ли у устройства гироскоп вообще?
enabled boolean Идут ли обновления сейчас?
attitude Quat Текущая ориентация. По умолчанию мировой фрейм — присваивай прямо в quaternion узла/камеры.
gravity Vec3 Направление гравитации в экранном пространстве (x → вправо, y → вниз), в g: −1 … 1 по каждой оси. Читай x/y для 2D-наклона.

start(options) принимает { interval?: number, frame?: "world" | "device" }. interval (секунды, по умолчанию 1/60) — нижняя граница: сенсор объединяет данные в фоне на частоте не ниже её, а ты каждый кадр берёшь самый свежий сэмпл, так что частота сенсора не обязана совпадать с частотой кадров. frame по умолчанию "world": attitude/gravity приходят уже преобразованными в Y-up мировое пространство движка (а gravity — в экранное) и учитывают ориентацию — поверни телефон в ландшафт, и камера сама останется вертикальной. Передай "device" для сырого фрейма сенсора, если хочешь считать сам.

attitude скорректирован от дрейфа, так что горизонт панорамы остаётся ровным сколько угодно долго.

HDR-дисплей: device.hdr

Более яркие блики на HDR-экране: device.hdr — то, что умеет дисплей, его расширенный динамический диапазон. На десктопе под macOS, в видимом окне на экране с запасом над белым SDR (XDR-панели Apple, внешний дисплей в режиме HDR), 3D-поверхность — float, и движок рендерит выше белого SDR: 1.0 — это белый UI и диффузной белой поверхности, а солнце, эмиссия и блики поднимаются до headroom раз выше.

Note

везде остальное 3D — SDR: iOS, Android, веб, веб-плеер, десктоп на Windows и Linux, скрытый или скриптовый запуск десктопа (render --desktop, test --desktop, flow), headless-тесты: available — false, headroom и maxHeadroom читаются как 1, а hdrchange никогда не срабатывает.

Выбирай контент по available, а не по headroom: available и maxHeadroom постоянны для окна (пик, которого может достичь его 3D-поверхность, известен уже тогда, когда строится первая сцена), а headroom живой — он растёт от 1 в первые секунды после запуска и следует за клавишами яркости и экраном под окном.

TypeScript
const fireball = new Particles({ emissive: device.hdr.available ? 8 : 3.5 })   // единицы после экспозиции: выше 1 на SDR обрезается

device.addEventListener('hdrchange', (h) => console.log('rendering to', h, '× SDR white'))
Член Тип Примечания
available boolean Может ли поверхность показать хоть что-то выше белого SDR (maxHeadroom > 1)? Выбирай контент по нему.
maxHeadroom number Пик дисплея в долях белого SDR (XDR-панель на 1600 нит сообщает до 16); постоянен для окна, 1 на SDR.
headroom number До какого уровня движок рендерит прямо сейчас, с шагом в полступени; ≥ 1. Изменение сообщает событие hdrchange (проверяется 4 раза в секунду, пока подписан слушатель).

Это факты о дисплее. Вид картинки на нём — насколько она тянется к пику (strength), куда ложится белый (paperWhite) — дело сцены: scene.postProcessing.hdr. Переменные окружения могут зафиксировать любой из них для A/B на реальной панели (LECODES_HDR_STRENGTH, LECODES_HDR_PAPER_WHITE, движок читает их на каждом нативном хосте): фиксация побеждает postProcessing.hdr любой сцены.

emissive частиц — в единицах после экспозиции (1 = белый на экране), и всё выше 1 на SDR обрезается — так что огненный шар, сделанный на 3.5 для SDR, на HDR — тот же шар, только без обрезки. Подними значение при available, чтобы ядро раскалилось добела.

Оверлей статистики: device.statsOverlay

Покажи частоту кадров на телефоне: device.statsOverlay = true рисует собственную строку цифр кадра хоста поверх всего; false её убирает.

TypeScript
device.statsOverlay = true                          // хост рисует свою строку цифр кадра поверх всего
console.log('overlay shown:', device.statsOverlay)  // false там, где у хоста его нет (веб, headless)

Строка для сборки на устройстве:

TypeScript
74 fps  64% even  cpu 1.0
Часть Смысл
fps 3D-кадров в секунду
even доля этих кадров, что продержались на экране самое частое число обновлений дисплея. Среднее это прячет: 66 fps 70% even — смесь коротких и длинных кадров, заметное дрожание, а 60 fps 100% even — плавно
cpu миллисекунды главного потока на кадр (твой код, раскладка, отправка кадра). Низкий fps при маленьком cpu значит, что упор в GPU

Хост измеряет и рисует строку сам, примерно раз в секунду; ничего из этого не выполняется в твоём коде, так что включение оверлея не меняет цифр, которые он показывает. Он принадлежит хосту, а не проекту — остаётся включённым, когда открыт другой проект, пока его не выставят в false.

Note

Android показывает всю строку; iOS — fps и cpu (без even); десктоп — свой счётчик кадров (тот, что рисует lecodes desktop run --fps). Без 3D-сцены телефоны показывают только cpu. У веба, безоконного сервера и headless-тестов оверлея нет: сеттер ничего не делает, а свойство читается как false.

Смотрите также

  • Даты — date().format, timeAgo: английский и русский
  • Сигналы — .stored(key) и реактивный текст, на котором держатся переводы
  • События указателя и жесты — события, которые питает точный тач
  • Input — клавиатура, мышь, геймпады и их вибрация
  • Соглашения — логические px, паттерн addEventListener