> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acondawayuno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dynamic Day/Night Lighting Driven by Your Timezone

> The Living Index reads your profile timezone to drive room lighting — sun arc, ambient light, fog, and indoor lamps all shift across day/night phases.

The Living Index 的 3D 房间会根据**你配置文件中的时区**计算当前当地时间，并用这个时间驱动整间房间的光照——太阳弧度、环境光色温、雾密度、窗户色彩和室内灯光随昼夜阶段平滑过渡。访客打开页面时看到的，是属于你当地时间的那个光照瞬间。

The Living Index 3D room reads your **profile timezone** to calculate the current local time, then uses that time to drive the entire room's lighting — sun arc, ambient light color temperature, fog density, window color, and indoor lamps all transition smoothly across day/night phases. When a visitor opens your page, they see the exact lighting moment that belongs to your local time.

***

## 时区来源：你的，不是访客的 / Timezone Source: Yours, Not the Visitor's

房间读取的时区来自你的**内容配置**中的 `profile.timezone` 字段，而不是访客设备的时区。无论访客身处何地，他们看到的都是你所在时区的当地时间光照。

The room reads the timezone from the `profile.timezone` field in your **content configuration** — not from the visitor's device timezone. Regardless of where a visitor is located, they see the lighting of your local time.

<CardGroup cols={2}>
  <Card title="IANA 时区格式 / IANA Timezone Format" icon="globe">
    支持标准 IANA 时区名称，例如：

    Supports standard IANA timezone names, for example:

    ```text theme={null}
    Asia/Shanghai
    America/New_York
    Europe/London
    Australia/Sydney
    ```
  </Card>

  <Card title="固定偏移格式 / Fixed Offset Format" icon="clock">
    也支持个人简介中常用的固定偏移写法，例如：

    Also supports fixed offset formats commonly used in personal profiles:

    ```text theme={null}
    GMT+8
    UTC-5
    GMT+9:30
    ```
  </Card>
</CardGroup>

***

## 如何设置时区 / How to Set Your Timezone

<Steps>
  <Step title="打开内容工作台 / Open Content Studio">
    启动本地开发服务器，然后在浏览器地址栏加入 `?studio=1` 打开内容工作台。

    Start the local dev server, then append `?studio=1` to the URL in your browser to open Content Studio.
  </Step>

  <Step title="进入个人资料区块 / Go to the Profile Section">
    在工作台左侧找到 **个人主页 / Profile** 区块，然后找到 **城市 / City** 或 **时区 / Timezone** 字段。

    In the left panel of Content Studio, find the **个人主页 / Profile** section, then locate the **City / Timezone** field.
  </Step>

  <Step title="输入你的时区 / Enter Your Timezone">
    填入 IANA 时区名称或固定偏移。输入会立即更新 Studio 预览；保持中英文时区一致。

    Enter an IANA timezone or fixed offset. The Studio preview updates immediately; keep Chinese and English timezone values aligned.
  </Step>

  <Step title="保存到项目 / Save to Project">
    点击 **保存到项目** 才会把预览持久化到项目。然后提交并推送。

    Click **Save to project** to persist the preview to the project, then commit and push.
  </Step>
</Steps>

<Note>
  IANA 时区（例如 `America/New_York`）会跟随夏令时；`GMT+8` 等固定偏移不会。`city` 只负责显示，不参与光照计算。非法时区会回退到 UTC。

  IANA zones such as `America/New_York` follow daylight-saving transitions. Fixed offsets such as `GMT+8` do not. `city` is display-only and does not drive lighting. Invalid zones fall back to UTC.
</Note>

***

## 昼夜光照阶段 / Day/Night Lighting Phases

房间将一天划分为四个光照阶段，每个阶段都有独特的光照氛围，相邻阶段之间平滑过渡。

The room divides the day into four lighting phases. Each phase has a distinct lighting atmosphere, and adjacent phases transition smoothly into each other.

<CardGroup cols={2}>
  <Card title="🌙 夜间 / Night" icon="moon">
    **室内灯光为主。/ Indoor lighting is primary.**

    吊灯与研究桌灯点亮，提供可探索性。月光以微弱蓝色环境光维持基本亮度，窗外一片深邃。

    The chandelier and desk lamp illuminate the room for explorability. Moonlight provides a faint blue ambient fill. The window exterior is deep and dark.
  </Card>

  <Card title="🌅 黎明 / Dawn" icon="sun">
    **暖橙色晨光从窗外渗入。/ Warm orange sunrise light filters through the windows.**

    自然光与室内灯光交叠，窗户色温逐渐从深蓝转为暖橙，雾密度开始降低。

    Natural and indoor light overlap. Window color temperature shifts gradually from deep blue to warm orange. Fog density begins to decrease.
  </Card>

  <Card title="☀️ 白昼 / Day" icon="sun">
    **明亮日光，太阳弧清晰。/ Bright sunlight with a clear sun arc.**

    环境光达到最强，色温为日光白，雾密度最低，房间整体最为明亮，室内灯光自动关闭。

    Ambient light is at its strongest with daylight white color temperature. Fog is at its lowest density. The room is at its brightest. Indoor lamps turn off automatically.
  </Card>

  <Card title="🌇 黄昏 / Dusk" icon="cloud-sun">
    **金黄色调，平滑过渡到室内灯光。/ Golden tones, smoothly transitioning back to indoor lighting.**

    太阳低悬，光线呈金橙色。雾密度开始回升，室内灯光随自然光减弱而逐渐点亮。

    The sun sits low with golden-orange light. Fog density begins to rise. Indoor lamps gradually brighten as natural light fades.
  </Card>
</CardGroup>

***

## 光照阶段影响的视觉元素 / Visual Elements Affected by Lighting Phase

每个光照阶段变化时，以下视觉元素都会同步更新：

When the lighting phase changes, the following visual elements update together:

| 视觉元素 / Visual Element                           | 变化方式 / How It Changes                                                                                           |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| 环境光强度与色彩 / Ambient light intensity & color      | 随阶段从蓝月光→暖橙→日光白→金橙平滑过渡 / Smoothly transitions from blue moonlight → warm orange → daylight white → golden orange |
| 太阳 / 月亮方向与强度 / Sun / moon direction & intensity | 太阳弧在白天沿天空运动，夜间切换为月光方向 / Sun arc moves across sky during day; switches to moonlight direction at night           |
| 雾密度 / Fog density                               | 夜间和黎明最高，白昼最低 / Highest at night and dawn, lowest during day                                                     |
| 窗户色温 / Window color temperature                 | 从夜间深蓝到黎明暖橙、白昼日光白、黄昏金橙 / From deep blue at night → warm orange at dawn → daylight white → golden orange at dusk  |
| 吊灯 / 研究桌灯 / Chandelier & desk lamp              | 夜间全亮，白昼关闭，晨昏阶段渐变 / Full brightness at night, off during day, gradual during transitions                         |
| 房间 HUD / Room HUD                               | 显示当前当地时间与光照阶段名称 / Shows current local time and lighting phase name                                              |

***

## 房间 HUD 上的时间与阶段信息 / Time and Phase Info in the Room HUD

房间 HUD（显示在房间界面内）会实时显示两项信息：

The room HUD (displayed within the room interface) shows two pieces of information in real time:

* **当前当地时间 / Current local time** — 根据 `profile.timezone` 计算的时钟
* **当前光照阶段 / Current lighting phase** — 例如 "夜间 / Night"、"白昼 / Day"

This gives visitors an immediate sense of what time it is in your world.

***

## 热更新：无需重建渲染器 / Hot Update: No Renderer Rebuild Required

在内容工作台修改时区后，光照系统会立即热更新，不会重建 Three.js 渲染器，也不会丢失当前的相机位置或已打开的章节。

After you update the timezone in Content Studio, the lighting system hot-updates immediately. The Three.js renderer is **not** rebuilt, and your current camera position and open chapter are preserved.

## Imported model lighting / 导入模型与光照

GLB mesh 会启用 cast/receive shadow，并保留导入材质。`MeshStandardMaterial` / `MeshPhysicalMaterial` 等 PBR 材质会响应昼夜光照；unlit、`MeshBasicMaterial` 或高强度 emissive 材质不会明显受场景灯影响。

Imported GLB meshes cast and receive shadows while retaining their authored materials. PBR materials such as `MeshStandardMaterial` and `MeshPhysicalMaterial` respond to day/night lighting. Unlit, `MeshBasicMaterial`, or strongly emissive materials do not respond visibly in the same way.

<Note>
  **关于光照精度 / A Note on Lighting Accuracy**

  当前实现是"当地时间驱动的风格化太阳弧"，采用稳定的晨昏时间区间，而不是天文意义上的精确日出 / 日落计算。这意味着它不会隐含地假设访客的纬度或所处半球，在全球任何地方都能稳定呈现一致的光照风格。

  The current implementation is a **stylized sun arc driven by local time**, using stable dawn/dusk intervals rather than astronomically precise sunrise/sunset calculations. This means it does not implicitly assume the visitor's latitude or hemisphere, producing consistent lighting anywhere in the world.

  如果你需要精确的日出时刻、日落时刻和太阳高度角，应在 `profile` 中增加 **纬度（latitude）** 和 **经度（longitude）**，再接入天文算法。

  If you need precise sunrise/sunset times and solar elevation angles, add **latitude** and **longitude** to your `profile` and connect an astronomical calculation library.
</Note>