Устройство
device — то, что приложение знает о телефоне или компьютере, на котором работает: платформа, язык
пользователя, размер экрана, сеть, хаптика и датчик движения — обычный глобальный объект.
Локализация строится на device.language; модуля переводов в SDK нет.
- выбрать управление касанием или мышью на телефоне, десктопе или в вебе
- показать приложение на языке пользователя и перевести его тексты
- форматировать числа, цены и даты для языка пользователя
- отзеркалить раскладку для арабского или иврита
- разложить экран под его размер — и заново, когда телефон повернули или окно изменило размер
- показать баннер, когда устройство ушло в офлайн
- дать вибрацию по тапу на кнопку
- рулить или осматриваться наклоном телефона
- показать частоту кадров на телефоне
Платформы: все хосты; хаптика и датчик движения — только на iOS и Android (в вебе — одно простое жужжание, без движения), HDR-картинка — только на десктопе под macOS (экран XDR) — проверяй device.motion.available / device.hdr.available.
Обзор
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 называет модель ввода, а не ОС.
device.platform // "ios" | "android" | "desktop" | "web" (только чтение)Windows, macOS и Linux все сообщают "desktop". Браузер сообщает "web" — и браузер телефона, и
браузер компьютера, поэтому веб-сборка предлагает оба вида управления, — и так же headless-тесты
(lecodes render / lecodes test).
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", — ключ, по которому выбираются тексты и форматы приложения. Он читается у хоста при каждом
обращении; события об изменении нет.
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" |
региона и письменности нет: британский и американский английский оба читаются как "en",
упрощённый и традиционный китайский — оба как "zh". Headless-тесты всегда идут на "en" —
остальные языки проверяй через собственный переключатель языка приложения
(ниже).
Перевод текстов приложения
Чтобы перевести тексты приложения на несколько языков, держи таблицу строк на каждый язык и выбирай
её по device.language, с английским как запасным — модуля переводов в SDK нет, это паттерн.
Сохраняемый сигнал помнит выбор языка пользователем между запусками.
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 передавай в
форматы чисел и дат.
не убирай стрелку: UIText(t('greeting')) читает текст один раз и больше не обновляется —
компилятор делает привязку только из прямого чтения .value сигнала
(сигналы).
Числа и цены в формате локали
Числа и цены с валютой форматируй под локаль пользователя своим кодом: форматтера чисел и валют в
SDK нет, а Intl не существует на Android, Windows и Linux — там toLocaleString('de-DE') печатает
голые цифры (1234567.5), а new Intl.NumberFormat() бросает исключение. На iOS, macOS, в браузерах
и headless-тестах Intl есть, так что тест разницы не покажет.
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() нет
названий месяцев:
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() нет немецких названий месяцевнеделя начинается с воскресенья (startOf('week')), и любая дата — в локальном времени
устройства; API часовых поясов нет.
Языки с письмом справа налево
Арабский, иврит, персидский и урду читаются справа налево, но раскладка всегда идёт слева направо: строка ставит первого потомка слева на любом хосте. Отзеркаливай экран для этих языков сам — разверни потомков строки и выровняй её тексты вправо:
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') отзеркаливает потомков контейнера, не меняя
их порядка.
iOS, Android и браузеры шейпят арабский текст и иврит и упорядочивают их внутри строки; десктоп (Windows, macOS, Linux) рисует их без шейпинга, буква за буквой слева направо — проверяй текст справа налево на телефоне.
Размер экрана и поворот: device.width, device.height, resize
Раскладывай приложение под экран, который у него есть: device.width × device.height — дисплей в
логических px, а событие resize сообщает новый размер после поворота или ресайза окна.
device.width // логические px (только чтение)
device.height // логические px (только чтение)
device.addEventListener('resize', (width, height) => { }) // логические px
device.removeEventListener('resize', callback) // та же ссылка на функциюОба — логические px (как clientX / clientY), никогда не физические пиксели. resize
срабатывает при каждом изменении; придёт ли ещё одно на старте, зависит от хоста (headless-тесты и
безоконный сервер его присылают), поэтому Обзор читает размер один раз и ещё раз в
resize.
оба могут читаться как 0, пока хост не сообщил размер — телефон может выполнить код
приложения до первой раскладки, поэтому размер читается снова в resize. Headless-тесты сразу
сообщают 390 × 844 (--width / --height его меняют).
Чтобы перестилизовать экран в ландшафте, классу стилей $landscape код не нужен
(классы); чтобы зафиксировать ориентацию, используй app.setOrientation
(app).
Плотность пикселей: device.pixelRatio
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 сообщают о каждом изменении.
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: мнение транспорта, которое
поддерживают его вызовы и его сокет.
iOS, Android, десктоп и веб сообщают об изменениях (десктоп проверяет каждые 2 с).
Headless-тесты и безоконный сервер читают true и никогда не шлют событий.
Точный тач для рисования: device.setPreciseTouch
device.setPreciseTouch(enabled: boolean) // выключен по умолчаниюБолее гладкие штрихи для рисования в 2D-сцене: с включённым точным тачем быстрый штрих доходит до событий указателя сцены на полной частоте сенсорного экрана (объединённые касания iOS, ≈120–240 Гц), а не раз в кадр дисплея (~60 Гц). Для UI из тапов и кнопок оставь его выключенным.
только iOS и только для событий указателя 2D-сцены (Scene2D) —
касания UI и 3D не меняются. Тихий no-op на Android, десктопе и в вебе.
Хаптика
Дай тактильный отклик, когда нажата кнопка, изменилось значение или действие удалось:
device.vibrate(style) выдаёт один короткий хаптик семантического стиля (по умолчанию
"medium").
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 — на одном телефоне это
слабый тик, на другом резкий щелчок; бери его, когда нужен именно этот нативный тап, а не сила.
iOS и Android. Веб даёт каждому стилю одно и то же короткое жужжание — там, где браузер вообще умеет вибрировать; десктоп и headless-тесты ничего не делают. Устройство без вибромотора (iPad) молчит, а системная настройка хаптики пользователя соблюдается. Вибрация геймпада — в Input.
Движение
Наклоняй телефон, чтобы рулить, или поворачивай, чтобы осматриваться: device.motion — датчик
движения, объединяющий гироскоп и акселерометр. Запусти его, затем читай gravity (наклон) или
attitude (ориентацию телефона) каждый кадр в update системы.
только iOS и Android. На десктопе, в вебе и в headless-тестах available — false,
start() резолвится в false, gravity читается как (0, 0, 0), а attitude — как
Quat.identity: дай этим хостам управление касанием или клавиатурой.
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, панорама) берёт ориентацию телефона:
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') }) // начать обновления (батарея)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 раз выше.
везде остальное 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 в первые секунды после запуска и следует за клавишами яркости и
экраном под окном.
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 её убирает.
device.statsOverlay = true // хост рисует свою строку цифр кадра поверх всего
console.log('overlay shown:', device.statsOverlay) // false там, где у хоста его нет (веб, headless)Строка для сборки на устройстве:
74 fps 64% even cpu 1.0| Часть | Смысл |
|---|---|
fps |
3D-кадров в секунду |
even |
доля этих кадров, что продержались на экране самое частое число обновлений дисплея. Среднее это прячет: 66 fps 70% even — смесь коротких и длинных кадров, заметное дрожание, а 60 fps 100% even — плавно |
cpu |
миллисекунды главного потока на кадр (твой код, раскладка, отправка кадра). Низкий fps при маленьком cpu значит, что упор в GPU |
Хост измеряет и рисует строку сам, примерно раз в секунду; ничего из этого не выполняется в твоём
коде, так что включение оверлея не меняет цифр, которые он показывает. Он принадлежит хосту, а не
проекту — остаётся включённым, когда открыт другой проект, пока его не выставят в false.
Android показывает всю строку; iOS — fps и cpu (без even); десктоп — свой счётчик
кадров (тот, что рисует lecodes desktop run --fps). Без 3D-сцены телефоны показывают только
cpu. У веба, безоконного сервера и headless-тестов оверлея нет: сеттер ничего не делает, а
свойство читается как false.
Смотрите также
- Даты —
date().format,timeAgo: английский и русский - Сигналы —
.stored(key)и реактивный текст, на котором держатся переводы - События указателя и жесты — события, которые питает точный тач
- Input — клавиатура, мышь, геймпады и их вибрация
- Соглашения — логические px, паттерн
addEventListener