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

# パスとモジュールキー

> ファイル名の文法、扱える拡張子、予約名、require のキーとの対応

## `.lua` のファイル名とフォルダ名

**Lua 識別子だけが使えます。**

```
[A-Za-z_][A-Za-z0-9_]*
```

使えるもの: `util` `lib` `pid_controller` `_internal` `nav2`
使えないもの: `my-lib` (ハイフン) `2d` (数字始まり) `ライブラリ` (非 ASCII) `my lib` (空白)

この制約があるおかげで、パスと `require` のキーが**常に1対1**で対応します。

| パス                | モジュールキー       |
| ----------------- | ------------- |
| `util.lua`        | `util`        |
| `lib/math.lua`    | `lib.math`    |
| `lib/nav/pid.lua` | `lib.nav.pid` |

区切りは `.` だけです。大文字と小文字は区別されます。
`require` の文字列とキーは完全一致で照合されます。変換や補完は行いません。

<Note>
  もしハイフンなどを許すと、`a/b.lua` と `a.b.lua` が同じキーになりうるため、
  どちらを読むべきか決められなくなります。文法の段階でこの曖昧さを消しています。
</Note>

## 扱える拡張子

| 拡張子                           | リント | 実行 | minify | 命名の制約         |
| ----------------------------- | --- | -- | ------ | ------------- |
| `.lua`                        | ○   | ○  | ○      | **Lua 識別子のみ** |
| `.md` `.txt` `.json` `.jsonl` | —   | —  | —      | 制約なし          |
| `.png` `.jpg` `.jpeg` `.webp` | —   | —  | —      | 制約なし。小文字のみ    |
| `.design`                     | ○   | ○  | ○      | 専用のノード型       |

`.lua` 以外に Lua 識別子の制約が無いのは、`require` の対象ではないためです。

<Note>
  画像は本文を持ちません。そのため通常の新規作成では作れず、画像として追加する必要があります。
  同じ理由で、画像とそれ以外を入れ替えるような名前変更も拒否されます。
</Note>

## 予約されている名前

| 名前              | 扱い                                                                      |
| --------------- | ----------------------------------------------------------------------- |
| フォルダ `sim`      | **作成できません** ([`sim.*` の名前空間](/storm-code/reference/sim-library)と衝突するため) |
| ファイル `sim.lua`  | どの階層にも置けます。ただし `require` の対象外です                                         |
| ルート直下の `.scode` | Storm Code の内部設定置き場として予約されています                                          |

### Design が作る仮想モジュール

[Design](/storm-code/guides/design) は、次の形のモジュールキーを生成します。

```
ui.pfd                    -- Orchestration 層
ui.pfd.monitor.<key>      -- Monitor 層
ui.pfd.view.<key>         -- パーツ層
```

**これらは実ファイルと衝突できません。**
ファイルや Design の作成・名前変更、パーツのキー変更のいずれでも、衝突する操作は拒否されます。

## `sim.lua` のカスケード

対象のファイルからルートへ向かってフォルダを遡り、途中にある `sim.lua` を集めます。
Stormworks のビークル / マイクロコントローラーのような3段構造はありません。

## `.scode` の中身

| パス                     | 内容                                         | 共同編集で同期されるか |
| ---------------------- | ------------------------------------------ | ----------- |
| `.scode/snippets.json` | [Design](/storm-code/guides/design) のスニペット | される         |

`.scode` 配下は緩い検証で扱われ、`.lua` の命名の制約は適用されません。