Scene refact4

AGENTS.md

@@ -228,6 +228,7 @@ Gemini rules:
 - Keep edits scoped to the requested behavior and related contracts.
 - Update `GDD.md` if gameplay/design behavior changes.
 - Use structured APIs/parsers where available instead of ad hoc string manipulation.
+- For parser command/debugging issues, use the running app when practical: enable `#PEEK-ON`, reproduce the command, and inspect `CONTEXT`, `SCOPE`, `ENVELOPE`, `CORE`, and `RESULT` before guessing.
 - For runtime/scene/gameplay bugs, prefer diagnostic helpers or temporary probes that explain engine decisions, such as why `isWalkable` returned false, which object blocked a path, or which semantic rule selected a parser target.
 - Do not revert user changes. Work with dirty files unless the user explicitly asks to revert them.
 

GDD.md

@@ -267,6 +267,7 @@ Parser обрабатывает пользовательский ввод кас
 ### Свойства сцены
 
 Сцена может поддерживать _Depth-scaling_ -- масштабирование объектов, имитирующее 3d перспективу, когда объекты, находящиеся "дальше от камеры" (то есть, выше по оси Y), становятся меньше. Настройки масштабирования для каждой сцены свои.
+Также у сцены есть _Correctional scale_ -- editor-level инструмент нормализации масштаба самой сцены. При изменении этого значения редактор масштабирует объекты сцены и их абсолютные координаты вокруг общего центра, чтобы относительное расположение объектов сохранялось. У Entity обычное поле _Scale_ является референсным размером объекта/префаба, не зависящим от сцены; при переносе объекта в сцену оно не умножается на Correctional scale. Поверх Scale всё ещё может применяться Depth-scaling и временные runtime-множители вроде `Subscene.itemScale`.
 Кроме того, объекты типа Static и Actor имеют свойство, запрещающее их Depth-scaling. Если Depth-scaling объекта запрещен, то он не изменяет свой размер при изменении Y, даже если Depth-scaling включен для сцены. Это полезно, например, для сцен, где персонаж лезет вертикально вверх по пожарной лестнице, и не должен уменьшаться по мере подъёма, поскольку не удаляется от камеры.
 
 Сцена имеет свойство, определяющее _положение "камеры"_ (viewport), т.е. задаёт какая область сцены будет отображаться на экране и с каким зумом. Например, при приближении персонажа игрока к краю экрана сцена скроллится. По умолчанию камера позиционируется на персонаже игрока, но позиционированием можно управлять и динамически, например если игрок выходит из дома на улицу, то масштаб изображения может уменьшиться кастомной логикой (скриптом) этой сцены, отдалив камеру чтобы передать ощущение большого открытого пространства.
@@ -387,7 +388,7 @@ Parser видит это так, как будто:
 
 Из этого следует правило: `on`/`under`/`behind` между вложенными значимыми объектами не отменяет их `in`-отношение к более внешнему контейнеру. Одно и то же дерево spatial-узлов может давать разные корректные текстовые отношения в зависимости от якоря запроса.
 
-Это правило используется не только для описаний, но и для relation-aware parser-действий. `TAKE Book B FROM Cabinet` может найти `Book B`, потому что относительно `Cabinet` она находится внутри шкафа; `TAKE Book B FROM Book A` тоже может быть допустимой естественной формулировкой, потому что `from` для `TAKE` трактуется как общий источник, а ближайшее конкретное отношение между `Book A` и `Book B` остаётся `on`. После semantic resolution все действия всё равно проходят обычные runtime-проверки расстояния, блокеров, closed/transparent Switch и возможности взять предмет.
+Это правило используется не только для описаний, но и для relation-aware parser-действий. `LOOK Cabinet` и `EXAMINE Cabinet` после основного текста перечисляют видимые titled-потомки по всем relations (`in`, `on`, `under`, `behind`) относительно `Cabinet`; `LOOK IN Cabinet` перечисляет только потомков в выбранном relation. `TAKE Book B FROM Cabinet` может найти `Book B`, потому что относительно `Cabinet` она находится внутри шкафа; `TAKE Book B FROM Book A` тоже может быть допустимой естественной формулировкой, потому что `from` для `TAKE` трактуется как общий источник, а ближайшее конкретное отношение между `Book A` и `Book B` остаётся `on`. После semantic resolution все действия всё равно проходят обычные runtime-проверки расстояния, блокеров, closed/transparent Switch и возможности взять предмет.
 
 Таким образом, технические spatial-узлы можно использовать для внутренней структуры сцены, не засоряя ими текстовый слой и не ломая parser-команды.
 
@@ -499,7 +500,7 @@ _Sort Mode_ (v0, v1, v2, v3, ignore)
 
 - _Exit_ (id сцены, id TriggerBox) : попадание в такой триггер вызывает перенос персонажа игрока в сцену с указанным id и в TriggerBox с id, указанном в компоненте. id сцены может указывать и на текущею сцену, тогда персонаж игрока будет телепортирован в TriggerBox текущей сцены.
 
-- _Entry_ (направление): Ответный триггер по отношению к Exit, он обозначает ту точку в сцене, куда перемещается Actor при переходе, а также направление, в котором он будет находиться при появлении.
+- _Entry_ (направление): Ответный триггер по отношению к Exit, он обозначает ту точку в сцене, куда перемещается Actor при переходе, а также направление, в котором он будет находиться при появлении. При входе через Entry Actor также получает `Layer` и `Parallax` этого Entry, чтобы портал контролировал глубинный слой входа. Если player Actor переходит в другую сцену, zoom камеры целевой сцены сбрасывается на её default camera zoom.
 
 - _Subscene_ (targetID: identifies object(s) to enable, [Name]: optional EXAMINE command keyword, [itemScale]: optional runtime scale multiplier for Items, see below) : Триггер, который при клике мышью или по команде `EXAMINE Name` открывает крупный план чего-то поверх затемнённой/заблюренной текущей сцены. Например, игрок кликает по столу и ему открывается крупный план стола как "картинка в картинке".
   Технически это просто включение (Enable) указанных целей. Для выхода обратно в главную сцену игрок должен кликнуть за пределами объектов этой группы.
@@ -611,10 +612,10 @@ Parser-команды `OPEN` и `CLOSE` используют тот же runtime
 
 - `hidden` (`false | lookable | examinable`) : семантическое поле titled-объекта.
   - `false`: обычное поведение;
-  - `lookable`: объект отсутствует в semantic world model, пока не будет раскрыт через `LOOK`-контекст, включая relation-look и mouse title reveal;
+  - `lookable`: объект отсутствует в semantic world model, пока не будет раскрыт через осмотр видимого anchor: `LOOK <anchor>`, relation-look (`LOOK UNDER <anchor>`), `EXAMINE <anchor>` или mouse title reveal;
   - `examinable`: объект отсутствует, пока не будет раскрыт успешным `EXAMINE`.
 
-  После раскрытия объект становится обычной семантической сущностью до конца текущей runtime-сессии сцены.
+  При первом раскрытии `lookable`-объекта через spatial-осмотр player-facing текст использует discovery-формулировку (`you discover`) вместо обычной visibility-формулировки (`you see`). После раскрытия объект становится обычной семантической сущностью до конца текущей runtime-сессии сцены, и последующие описания используют обычный `you see`.
 
 - _State_ () : Состояние объекта, например открыт/закрыт, включено/выключено, etc.
   Состояния это по сути переменные или свойства объекта, которые могут быть изменены скриптом. Они имеют поля:
@@ -766,6 +767,7 @@ Hero.walkTo(100, 100);
 - `game.playSound(filename: string)`: проигрывает звук из `public/sounds`;
 - `game.sceneManager.currentScene`: ссылка на текущую сцену;
 - `game.sceneManager.switchTo(sceneId: string)`: переключает игру на другую сцену;
+- `game.sceneManager.transferActorToScene(actor, targetSceneId, options?)`: переносит Actor-а в другую сцену централизованным путём вместе с его inventory/spatial-owned Entity descendants;
 - `game.inventory`: массив предметов в инвентаре игрока.
 
 Пример:
@@ -860,6 +862,7 @@ if (outcome.status === 'needs_clarification' && outcome.message) {
 - `api.getEntity(name: string)`: возвращает объект сцены по имени;
 - `api.getActor(name: string)`: возвращает `Actor` по имени;
 - `api.getQuad(name: string)`: возвращает `QuadObject` по имени;
+- `api.transferActor(actorName: string, targetSceneId: string, targetEntryId?: string)`: переносит Actor-а через `SceneManager.transferActorToScene`;
 - `api.setTimeout(...)`, `api.clearTimeout(...)`: таймеры;
 - `api.setInterval(...)`, `api.clearInterval(...)`: интервалы;
 - `api.saveCheckpoint()`: сохраняет текущее состояние сцены в undo history редактора.
@@ -1067,7 +1070,9 @@ F1 Game F2 Save F3 Load F4 New F5 Sprite Edit F9 Settings
 - _New_: Создаёт новую сцену из файла шаблона (default).
   Если текущая сцена содержит несохранённые изменения, перед созданием или загрузкой новой сцены открывается системный поп-ап подтверждения.
 - _Sprite_: Переход в редактор спрайтов.
-- _Settings_: Открывает в правой панели глобальные настройки игры. Сейчас они ограничены только настройками шейдера CRT:
+- _Settings_: Открывает в правой панели глобальные настройки игры:
+  - _Attached Volume_: глобальная коррекция громкости только для звуков, присоединённых к объектам сцены. Значение 1.0 оставляет авторскую громкость без изменений.
+  - _CRT settings_: настройки шейдера CRT:
   - _CRT MODE on/off_: включает/выключает все эффекты CRT (серый фон, искажения, scanlines, abberations)
   - _CRT geometry_: задаёт степень "выпуклости" экрана
   - _CRT scanlines_: размер scanlines
@@ -1103,6 +1108,7 @@ Prefab можно загрузить в текущую сцену из файл
 - _ID cцены_ (оно же имя файла при сохранении)
 - _Переключатель Depth scaling_ (on/off)
 - _Настройки Depth scaling_ (мин и макс. умножители масштаба, уровень горизонта и уровень переднего плана)
+- _Correctional scale_ в подсекции Correction: общий scene-level поправочный множитель для `Scale` объектов. При изменении этого значения редактор масштабирует все объекты сцены, включая locked, и их абсолютные координаты вокруг общего центра, чтобы относительное расположение объектов сохранялось.
 - _Настройки камеры_: текущие X/Y-координаты и Zoom, дефолтные координаты/Zoom, переключатель автоматического центрирования камеры на игрока, настройки автоцентрирования, настройки Depth scaling.
   Настройки камеры могут меняться как через редактор, так и динамически, прямо в игре, через игровую логику. Например, в кат-сцене камера может сделать zoom-out, переместиться с игрока на другой объект, а затем вернуться обратно и восстановить zoom.
   Если включено автоматическое центрирование, камера перемещается когда игрок подходим к краю экрана, что для пользователя выглядит как скроллинг.

InventorySys.md

@@ -60,6 +60,8 @@ Spatial relation внешнего контейнера/поверхности с
 Мы меняем реализацию компонента Inventory так, что находящиеся в них предметы теперь участвуют в иерархии сцены и видны там как дочерние объекты своих контейнеров (это относится и к предметам в инвентаре у игрока). Они имеют spatial relation "IN".
 Предметы, находящиемя в каком-то инвентаре, исключены из рендеринга и игре не отображаются. В панели иерархии в редакторе они видны, но имеют другой цвет, похожий на тот, что у disabled объектов, однако без перечёркнутой иконки как у disabled.  Таким образом, если надо включить предмет в инвентарь или исключить его оттуда -- это можно сделать прямо в редакторе.
 
+При `TAKE` движок переносит в Inventory тот же самый scene object. Он не создаёт копию предмета для инвентаря и не оставляет отдельный оригинал/дубликат в сцене. Меняется только storage ownership: предмет остаётся частью сцены, становится hidden для render layer и получает spatial placement `IN` относительно владельца Inventory.
+
 При этом для parser/text layer важно не отношение предмета к самому inventory-узлу, а spatial relation inventory-слота относительно его значимого владельца. Например, если у шкафа есть built-in Inventory с relation `BEHIND`, а книга технически находится как `IN`-ребёнок шкафа, то в текстовом слое книга считается находящейся `BEHIND the Cabinet`.
 
 Команды парсера типа TAKE FROM или PUT INTO работают с внешним (по отношению к персонажу игрока) инвентарём как с IN контейнером, если Inventory не имеет свойства Protected. В противном случае он недоступен в текстовом слое игры (за исключением случая, когда это Inventory самого игрока).