fix manuals (#569)

docs/en/manuals/camera.md

@@ -48,6 +48,13 @@ Orthographic Projection
 Orthographic Zoom
 : (**Orthographic camera only**) - The zoom used for the orthographic projection (> 1 = zoom in, < 1 = zoom out).
 
+Orthographic Mode
+: (**Orthographic camera only**) - Controls how the orthographic camera determines zoom relative to the window size and your design resolution (the values in `game.project` → `display.width/height`).
+  - `Fixed` (uses constant zoom): Uses the current `Orthographic Zoom` value as-is.
+  - `Auto Fit` (contain): Automatically adjusts zoom so the full design area fits inside the window. May show extra content on sides or top/bottom.
+  - `Auto Cover` (cover): Automatically adjusts zoom so the design area covers the entire window. May crop on sides or top/bottom.
+  Available only when `Orthographic Projection` is enabled.
+
 
 ## Using the camera
 
@@ -83,9 +90,11 @@ The scripting `camera` module has multiple functions that can be used to manipul
 camera.get_aspect_ratio(camera) -- get aspect ratio
 camera.get_far_z(camera) -- get far z
 camera.get_fov(camera) -- get field of view
+camera.get_orthographic_mode(camera) -- get orthographic mode (one of camera.ORTHO_MODE_*)
 camera.set_aspect_ratio(camera, ratio) -- set aspect ratio
 camera.set_far_z(camera, far_z) -- set far z
 camera.set_near_z(camera, near_z) -- set near z
+camera.set_orthographic_mode(camera, camera.ORTHO_MODE_AUTO_FIT) -- set orthographic mode
 ... And so forth
 ```
 
@@ -125,7 +134,7 @@ The view matrix provided by the camera defines the position and orientation of t
 
 ### Render script
 
-Starting with Defold 1.9.6, when using the default render script Defold will automatically set the last enabled camera that should be used for rendering. Before this change, a script somewhere in the project needed to explicitly send the `use_camera_projection` message to the renderer to notify it that the view and projection from camera components should be used. This is no longer necessary, but it is still possible to do so for backwards compatibility purposes.
+When using the default render script Defold will automatically set the last enabled camera that should be used for rendering. Before this change, a script somewhere in the project needed to explicitly send the `use_camera_projection` message to the renderer to notify it that the view and projection from camera components should be used. This is no longer necessary, but it is still possible to do so for backwards compatibility purposes.
 
 Alternatively, you can set a specific camera that should be used for rendering in a render script. This could be useful in cases where you need to control more specifically which camera should be used for rendering, for example in a multiplayer game.
 
@@ -163,6 +172,22 @@ You can zoom in and out when using an orthographic camera by changing the *Ortho
 go.set("#camera", "orthographic_zoom", 2)
 ```
 
+When using an orthographic camera you can also switch how zoom is determined using the `Orthographic Mode` setting or via script:
+
+```lua
+-- get current mode (one of camera.ORTHO_MODE_FIXED, _AUTO_FIT, _AUTO_COVER)
+local mode = camera.get_orthographic_mode("#camera")
+
+-- switch to auto-fit (contain) to always keep the full design area visible
+camera.set_orthographic_mode("#camera", camera.ORTHO_MODE_AUTO_FIT)
+
+-- switch to auto-cover to ensure the design area covers the window
+camera.set_orthographic_mode("#camera", camera.ORTHO_MODE_AUTO_COVER)
+
+-- switch back to fixed mode to control zoom manually via orthographic_zoom
+camera.set_orthographic_mode("#camera", camera.ORTHO_MODE_FIXED)
+```
+
 ### Adaptive zoom
 
 The concept behind adaptive zoom is to adjust the camera zoom value when the resolution of the display change from the initial resolution set in *game.project*.
@@ -202,6 +227,8 @@ end
 
 A complete example of adaptive zoom can be seen in [this sample project](https://github.com/defold/sample-adaptive-zoom).
 
+Note: With an orthographic camera you can now achieve contain/cover behavior without custom code by setting `Orthographic Mode` to `Auto Fit` (contain) or `Auto Cover` (cover). In these modes the effective zoom is computed automatically based on window size and your design resolution.
+
 
 ### Following a game object
 
@@ -264,13 +291,13 @@ A camera has a number of different properties that can be manipulated using `go.
 : The orthographic camera zoom (`number`).
 
 `aspect_ratio`
-: Added in Defold 1.4.8. The ratio between the frustum width and height. Used when calculating the projection of a perspective camera. (`number`).
+: The ratio between the frustum width and height. Used when calculating the projection of a perspective camera. (`number`).
 
 `view`
-: Added in Defold 1.4.8. The calculated view matrix of the camera. READ ONLY. (`matrix4`).
+: The calculated view matrix of the camera. READ ONLY. (`matrix4`).
 
 `projection`
-: Added in Defold 1.4.8. The calculated projection matrix of the camera. READ ONLY. (`matrix4`).
+: The calculated projection matrix of the camera. READ ONLY. (`matrix4`).
 
 
 ## Third-party camera solutions

docs/en/manuals/debugging-game-and-system-logs.md

@@ -10,7 +10,7 @@ The game log shows all of the output from the engine, native extensions and your
 System logs are generated by the operating system and it can provide additional information that can help you pinpoint a problem. The system logs can contain stack traces for crashes and low memory warnings.
 
 ::: important
-The game log will only show information in debug builds. The log will be completely empty in release builds.
+Console/on-screen logging only shows information in Debug builds. In Release builds the console log is empty, but you can enable file logging in Release by setting the project setting "Write Log File" to "Always". See details below.
 :::
 
 ## Reading the game log from the editor
@@ -87,7 +87,13 @@ This will install the app on your device, start it and automatically attach a LL
 
 ## Reading the game log from the log file
 
-If you enable the *Write Log* setting in *game.project*, any game output will be written to disk, to a file called "`log.txt`". Here is how you extract the file if you run the game on device:
+Use the project setting "Write Log File" in *game.project* to control file logging:
+
+- "Never": Do not write a log file.
+- "Debug": Write a log file only for Debug builds.
+- "Always": Write a log file for both Debug and Release builds.
+
+When enabled, any game output will be written to disk to a file named "`log.txt`". Here is how you extract the file if you run the game on device:
 
 iOS
 : Connect your device to a computer with macOS and Xcode installed.

docs/en/manuals/project-settings.md

@@ -66,8 +66,14 @@ Publisher name.
 #### Developer
 Developer name.
 
-#### Write Log
-When checked, the engine will write a log file. If running more than one instance from the editor the file will be named *instance_2_log.txt* with `2` being the instance index. If running a single instance or from a bundle the file will be named *log.txt* The location of the log file will be one of the following paths (tried in order):
+#### Write Log File
+Controls when the engine writes a log file. Options:
+
+- "Never": Do not write a log file.
+- "Debug": Write a log file only for Debug builds.
+- "Always": Write a log file for both Debug and Release builds.
+
+If running more than one instance from the editor the file will be named *instance_2_log.txt* with `2` being the instance index. If running a single instance or from a bundle the file will be named *log.txt*. The location of the log file will be one of the following paths (tried in order):
 
 1. The path specified in *project.log_dir* (hidden setting)
 2. The system log path:

docs/en/manuals/render.md

@@ -137,6 +137,20 @@ msg.post("@render:", "use_fixed_projection", { near = -1, far = 1, zoom = 2 })
 
 When using the default render script and there are enabled [Camera components](/manuals/camera) available in the project, they will take precedence over any other view / projections set in the render script. To read more about how to work with camera components in render scripts, please consult the [Camera documentation](/manuals/camera).
 
+Orthographic cameras support an `Orthographic Mode` that controls how the camera adapts to the window:
+- `Fixed` uses the camera’s `Orthographic Zoom` value.
+- `Auto Fit` (contain) keeps the full design area visible.
+- `Auto Cover` (cover) fills the window and may crop.
+
+You can switch modes in the Editor or at runtime via the Camera API:
+
+```lua
+-- Use auto-fit behavior with an orthographic camera
+camera.set_orthographic_mode("main:/go#camera", camera.ORTHO_MODE_AUTO_FIT)
+-- Query current mode
+local mode = camera.get_orthographic_mode("main:/go#camera")
+```
+
 ## Frustum culling
 
 The render API in Defold lets developers perform something called frustum culling. When frustum culling is enabled any graphics that lies outside of a defined bounding box or frustum will be ignored. In a large game world where only a portion is visible at a time, frustum culling can dramatically reduce the amount of data that needs to be sent to the GPU for rendering, thus increasing performance and saving battery (on mobile devices). It is common to use the view and projection of the camera to create the bounding box. The default render script uses the view and projection (from the camera) to calculate a frustum.

docs/pl/manuals/project-settings.md

@@ -21,12 +21,25 @@ Tytuł aplikacji
 #### Version
 Wersja aplikacji
 
-#### Write Log
-Kiedy opcja zapisu logów jest zaznaczona, silnik zapisze wszystkie logi do pliku *log.txt* w głównej lokalizacji Twojego projektu. Gdy uruchomisz grę na systemie iOS, plik można będzie otworzyć przez iTunes w zakładce *Apps* w sekcji *File Sharing*. W systemie Android natomiast, plik jest przechowywany w zewnętrznej lokalizacji aplikacji (ang. app's external storage). Podczas uruchamiania aplikacji deweloperskiej *dmengine*, możesz podejrzeć logi używając komendy:
-
-```bash
-$ adb shell cat /mnt/sdcard/Android/data/com.defold.dmengine/files/log.txt
-```
+#### Write Log File
+Określa, kiedy silnik zapisuje log do pliku. Opcje:
+
+- "Never": nie zapisuj pliku logu.
+- "Debug": zapisuj plik logu tylko dla buildów Debug.
+- "Always": zapisuj plik logu zarówno dla buildów Debug, jak i Release.
+
+Jeśli uruchamiasz więcej niż jedną instancję z edytora, plik będzie nazwany *instance_2_log.txt*, gdzie `2` to indeks instancji. Jeśli uruchamiasz pojedynczą instancję lub paczkę, plik będzie nazwany *log.txt*. Lokalizacja pliku logu będzie jedną z poniższych (sprawdzane w tej kolejności):
+
+1. Ścieżka określona w *project.log_dir* (ukryte ustawienie)
+2. Systemowa ścieżka logów:
+   * macOS/iOS: `NSDocumentDirectory`
+   * Android: `Context.getExternalFilesDir()`
+   * Inne: katalog aplikacji
+3. Ścieżka wsparcia aplikacji:
+   * macOS/iOS: `NSApplicationSupportDirectory`
+   * Windows: `CSIDL_APPDATA` (np. `C:\Users\<username>\AppData\Roaming`)
+   * Android: `Context.getFilesDir()`
+   * Linux: zmienna środowiskowa `HOME`
 
 #### Compress Archive
 Umożliwia kompresowanie archiwów podczas budowania paczki. Zauważ, że dotyczy to wszystkich platform oprócz systemu Android, gdzie plik apk zawiera od razy skompresowane dane.

docs/ru/manuals/camera.md

@@ -48,6 +48,13 @@ Orthographic Projection
 Orthographic Zoom
 : (**Только для ортографической камеры**) — масштаб ортографической проекции (> 1 = приближение, < 1 = отдаление).
 
+Orthographic Mode
+: (**Только для ортографической камеры**) — управляет тем, как ортографическая камера определяет зум относительно размера окна и ваших значений дизайна (`game.project` → `display.width/height`).
+  - `Fixed` (постоянный зум): используется текущее значение `Orthographic Zoom`.
+  - `Auto Fit` (вписать): автоматически подбирает зум так, чтобы вся дизайн-область помещалась в окно. Возможен дополнительный контент по бокам/сверху/снизу.
+  - `Auto Cover` (заполнить): автоматически подбирает зум так, чтобы дизайн-область заполняла окно целиком. Возможна обрезка по бокам/сверху/снизу.
+  Доступно только при включённой `Orthographic Projection`.
+
 
 ## Использование камеры
 
@@ -83,9 +90,11 @@ render.set_camera()
 camera.get_aspect_ratio(camera)        -- получить соотношение сторон
 camera.get_far_z(camera)               -- получить дальнюю плоскость отсечения
 camera.get_fov(camera)                 -- получить угол обзора
+camera.get_orthographic_mode(camera)   -- получить ортографический режим (одно из camera.ORTHO_MODE_*)
 camera.set_aspect_ratio(camera, ratio) -- установить соотношение сторон
 camera.set_far_z(camera, far_z)        -- установить дальнюю плоскость отсечения
 camera.set_near_z(camera, near_z)      -- установить ближнюю плоскость отсечения
+camera.set_orthographic_mode(camera, camera.ORTHO_MODE_AUTO_FIT) -- установить ортографический режим
 ... и другие
 ```
 
@@ -163,6 +172,22 @@ end
 go.set("#camera", "orthographic_zoom", 2)
 ```
 
+Также для ортографической камеры можно выбрать способ определения зума с помощью параметра `Orthographic Mode` или из кода:
+
+```lua
+-- текущий режим (одно из: camera.ORTHO_MODE_FIXED, _AUTO_FIT, _AUTO_COVER)
+local mode = camera.get_orthographic_mode("#camera")
+
+-- включить режим "вписать" (contain), чтобы дизайн-область всегда полностью помещалась в окно
+camera.set_orthographic_mode("#camera", camera.ORTHO_MODE_AUTO_FIT)
+
+-- включить режим "заполнить" (cover), чтобы окно всегда было заполнено
+-- camera.set_orthographic_mode("#camera", camera.ORTHO_MODE_AUTO_COVER)
+
+-- вернуть "фиксированный" режим и управлять масштабом вручную через orthographic_zoom
+-- camera.set_orthographic_mode("#camera", camera.ORTHO_MODE_FIXED)
+```
+
 ### Адаптивный зум
 
 Адаптивный зум — это изменение значения зума камеры при изменении разрешения экрана относительно первоначального разрешения, заданного в *game.project*.
@@ -202,6 +227,8 @@ end
 
 Полный пример адаптивного зума доступен в [этом примерном проекте](https://github.com/defold/sample-adaptive-zoom).
 
+Примечание: Для ортографической камеры типичное поведение «вписать/заполнить» можно получить без пользовательского кода, установив `Orthographic Mode` в `Auto Fit` (вписать) или `Auto Cover` (заполнить). В этих режимах эффективный зум рассчитывается автоматически на основе размера окна и заданного разрешения дизайна.
+
 
 ### Следование за игровым объектом
 
@@ -264,13 +291,13 @@ end
 : Масштаб ортографической камеры (`number`).
 
 `aspect_ratio`
-: Добавлено в Defold 1.4.8. Соотношение ширины и высоты усечённой пирамиды. Используется при вычислении проекции перспективной камеры. (`number`).
+: Соотношение ширины и высоты усечённой пирамиды. Используется при вычислении проекции перспективной камеры. (`number`).
 
 `view`
-: Добавлено в Defold 1.4.8. Вычисленная матрица вида камеры. ТОЛЬКО ДЛЯ ЧТЕНИЯ. (`matrix4`).
+: Вычисленная матрица вида камеры. ТОЛЬКО ДЛЯ ЧТЕНИЯ. (`matrix4`).
 
 `projection`
-: Добавлено в Defold 1.4.8. Вычисленная матрица проекции камеры. ТОЛЬКО ДЛЯ ЧТЕНИЯ. (`matrix4`).
+: Вычисленная матрица проекции камеры. ТОЛЬКО ДЛЯ ЧТЕНИЯ. (`matrix4`).
 
 
 ## Сторонние решения для камеры

docs/ru/manuals/debugging-game-and-system-logs.md

@@ -10,7 +10,7 @@ brief: В этом руководстве объясняется, как чит
 Системные логи создаются операционной системой и могут содержать дополнительную информацию, которая может помочь вам выявить проблему. Системные логи могут содержать трассировки стека для сбоев и предупреждений о нехватке памяти. 
 
 ::: important
-В логе игры будет отображаться информация только в отладочных сборках. В сборках релизов лог будет полностью пустым. 
+Вывод в консоль/на экран показывается только в Debug-сборках. В Release-сборках консольный лог пуст, но вы можете включить запись лога в файл для Release, установив в настройках проекта параметр "Write Log File" в значение "Always". Подробнее см. ниже.
 :::
 
 ## Чтение лога игры из редактора 
@@ -87,7 +87,13 @@ $ ios-deploy --debug --bundle <path_to_game.app> # ВНИМАНИЕ: не .ipa
 
 ## Чтение лога игры из файла лога 
 
-Если вы включите параметр *Write Log* в *game.project*, любой вывод игры будет записываться на диск в файл с именем "log.txt". Вот как можно извлечь файл, если вы запускаете игру на устройстве: 
+Используйте параметр проекта "Write Log File" в *game.project*, чтобы управлять записью лога в файл:
+
+- "Never": не записывать лог в файл.
+- "Debug": записывать файл лога только для Debug-сборок.
+- "Always": записывать файл лога как для Debug, так и для Release-сборок.
+
+Если запись включена, весь вывод игры будет записываться на диск в файл "`log.txt`". Вот как можно извлечь файл, если вы запускаете игру на устройстве: 
 
 iOS
 : Подключите ваше устройство к компьютеру с установленными macOS и Xcode.

docs/ru/manuals/project-settings.md

@@ -66,8 +66,14 @@ local gravity_y = sys.get_config_number("physics.gravity_y")
 #### Developer
 Название разработчика.
 
-#### Write Log
-Если опция отмечена, движок будет записывать файл журнала. Если запущено несколько экземпляров из редактора, файл будет называться *instance_2_log.txt*, где `2` — индекс экземпляра. Если запущен один экземпляр или используется сборка, файл будет называться *log.txt*. Файл журнала будет сохранён в одном из следующих путей (в порядке приоритета):
+#### Write Log File
+Определяет, когда движок записывает файл журнала. Параметры:
+
+- "Never": не записывать лог в файл.
+- "Debug": записывать файл лога только для Debug-сборок.
+- "Always": записывать файл лога как для Debug, так и для Release-сборок.
+
+Если запущено несколько экземпляров из редактора, файл будет называться *instance_2_log.txt*, где `2` — индекс экземпляра. Если запущен один экземпляр или используется бандл, файл будет называться *log.txt*. Файл журнала будет сохранён в одном из следующих путей (в порядке приоритета):
 
 1. Путь, указанный в *project.log_dir* (скрытая настройка)
 2. Системный путь к журналам:

docs/ru/manuals/render.md

@@ -137,6 +137,20 @@ msg.post("@render:", "use_fixed_projection", { near = -1, far = 1, zoom = 2 })
 
 Когда используется рендер-скрипт по умолчанию и в проекте есть активированные [компоненты камеры](/manuals/camera), они имеют приоритет над любыми другими настройками вида и проекции, заданными в рендер-скрипте. Подробнее о работе с компонентами камеры в рендер-скриптах читайте в [документации по камере](/manuals/camera).
 
+Ортографические камеры поддерживают параметр `Orthographic Mode`, который управляет тем, как камера адаптируется к окну:
+- `Fixed` — используется значение `Orthographic Zoom` камеры.
+- `Auto Fit` (вписать) — вся дизайн-область остаётся видимой.
+- `Auto Cover` (заполнить) — окно заполняется целиком, возможна обрезка.
+
+Переключать режим можно в редакторе или во время выполнения через Camera API:
+
+```lua
+-- Использовать режим "вписать" для ортографической камеры
+camera.set_orthographic_mode("main:/go#camera", camera.ORTHO_MODE_AUTO_FIT)
+-- Узнать текущий режим
+local mode = camera.get_orthographic_mode("main:/go#camera")
+```
+
 ## Отсечение по усеченному конусу (Frustum culling)
 
 API рендеринга в Defold позволяет разработчикам использовать усечение по усеченному конусу. Когда усечение включено, вся графика, находящаяся вне заданной ограничивающей рамки или пирамиды вида (frustum), будет проигнорирована. В большом игровом мире, где одновременно отображается только часть контента, усечение может значительно сократить объем данных, передаваемых в GPU, тем самым повысив производительность и экономя заряд батареи (на мобильных устройствах). Обычно для создания ограничивающей рамки используется вид и проекция камеры. Рендер-скрипт по умолчанию использует вид и проекцию (от камеры) для расчета frustum.

docs/zh/manuals/debugging-game-and-system-logs.md

@@ -10,7 +10,7 @@ brief: 本手册解释了如何读取游戏和系统日志。
 系统日志由操作系统生成，它可以提供帮助您定位问题的附加信息。系统日志可以包含崩溃的堆栈跟踪和低内存警告。
 
 ::: important
-游戏日志只会在调试构建中显示信息。在发布构建中，日志将完全为空。
+控制台/屏幕上的日志仅在 Debug 构建中显示。在 Release 构建中控制台日志为空，但可以通过将项目设置“Write Log File”设为“Always”来启用 Release 的文件日志。详见下文。
 :::
 
 ## 从编辑器读取游戏日志
@@ -87,7 +87,13 @@ $ ios-deploy --debug --bundle <path_to_game.app> # 注意: 不是 .ipa 文件
 
 ## 从日志文件读取游戏日志
 
-如果您在*game.project*中启用*Write Log*设置，任何游戏输出都将写入磁盘，到一个名为"`log.txt`"的文件中。以下是在设备上运行游戏时如何提取文件的方法：
+使用 *game.project* 中的“Write Log File”设置控制是否写入日志文件：
+
+- “Never”：不写入日志文件。
+- “Debug”：仅在 Debug 构建中写入日志文件。
+- “Always”：在 Debug 和 Release 构建中都写入日志文件。
+
+启用后，任何游戏输出都会写入磁盘中的“`log.txt`”。以下是在设备上运行游戏时如何提取该文件：
 
 iOS
 : 将设备连接到安装了macOS和Xcode的计算机上。

docs/zh/manuals/project-settings.md

@@ -66,8 +66,14 @@ local gravity_y = sys.get_config_number("physics.gravity_y")
 #### Developer
 开发商名称。
 
-#### Write Log
-勾选时，引擎将写入日志文件。如果从编辑器运行多个实例，文件将被命名为 *instance_2_log.txt*，其中 `2` 是实例索引。如果运行单个实例或从打包运行，文件将被命名为 *log.txt*。日志文件的位置将是以下路径之一（按顺序尝试）：
+#### Write Log File
+控制引擎何时写入日志文件。选项：
+
+- “Never”：不写入日志文件。
+- “Debug”：仅在 Debug 构建中写入日志文件。
+- “Always”：在 Debug 和 Release 构建中都写入日志文件。
+
+如果从编辑器运行多个实例，文件将被命名为 *instance_2_log.txt*，其中 `2` 是实例索引。如果运行单个实例或从打包运行，文件将被命名为 *log.txt*。日志文件的位置将是以下路径之一（按顺序尝试）：
 
 1. 在 *project.log_dir* 中指定的路径（隐藏设置）
 2. 系统日志路径：