Update documentation to enhance clarity on native language and skill generation
ci / server (push) Failing after 3m37s
ci / client (push) Successful in 14s

- Revised `AGENTS.md` to specify that the same seed, map, name set, and native language must produce the same roster in tests.
- Updated `protocol.md` to clarify that everyone in the school is generated with the selected native language, and related languages may appear at a low skill.
- Enhanced `ai.md` to explain skill growth mechanics based on state and the introduction of minimum ranges for skills not yet acquired.
- Improved `people.md` to detail the generation of skills and traits, emphasizing that not every person receives every skill and the implications of body attributes on skill acquisition.
- Adjusted `projects.md` to reflect the inclusion of native language in roster generation, ensuring comprehensive documentation of project components.
This commit is contained in:
Leonid Pershin
2026-08-19 22:27:20 +03:00
parent 5a00ad7746
commit a441ed9763
5 changed files with 51 additions and 23 deletions
+37 -16
View File
@@ -138,7 +138,9 @@
Пять новых видов. Ссылки — строками `defName`, как везде.
1. **SkillDef** — навык. Диапазон, распределение при генерации, зависимость от возраста,
ограничения со стороны тела (см. ниже).
ограничения со стороны тела (см. ниже). Не каждый человек получает каждый навык:
`always` — у всех, предметы — по параллели ученика, `work` — только взрослым,
`adultChance` — шанс у взрослого поверх родного языка.
2. **TraitDef** — черта. Вес (частота), список несовместимых черт, ограничения по роли и возрасту,
модификаторы навыков.
3. **BodyAttributeDef** — свойство тела. Либо число с распределением (рост, вес), либо выбор из
@@ -153,14 +155,15 @@
| Вид | Ванильное содержание |
| --- | --- |
| Навыки | Школьные предметы (математика, русский, литература, физика, история, физкультура…) и физические (ловкость, сила, выносливость) |
| Навыки | Школьные предметы, языки набора имён, общение, физические (ловкость, сила, выносливость) и рабочие (педагогика, медицина, кухня…) |
| Черты | Около десяти для начала: усидчивый, рассеянный, задира, тихоня, лидер, лентяй, любопытный, вспыльчивый, добрый, аккуратный |
| Тело | Рост, вес, цвет волос, цвет глаз |
| Нужды | Сон, голод, туалет, общение |
Слои одинаковы у всех ролей. У неработающего родителя те же навыки и черты, что у ученика: урезать
их дешевле по памяти и дороже в коде — иначе каждое место, читающее навык, начинается с вопроса
«а есть ли он у этого человека».
Слои одинаковы у всех ролей: у родителя те же *виды* данных, что у ученика. Набор ключей
навыков — нет. Нет ключа — нет навыка, а не ноль: карточка его не показывает, урок, если
предмет всё же начался, стартует с `Range.Min`. Иначе первоклассник носил бы химию «для
полноты», а код всё равно спрашивал бы, есть ли она.
### Как тело ограничивает навыки
@@ -181,9 +184,14 @@
}
```
Генератор сначала бросает тело, потом навык, потом применяет ограничения как зажим. Порядок важен
и фиксируется: **тело первично**, навык подстраивается. Иначе один и тот же сид даст разных людей
в зависимости от порядка перебора.
Генератор сначала бросает тело, потом те навыки, которые человеку положены, потом применяет
ограничения как зажим. Порядок важен и фиксируется: **тело первично**, навык подстраивается.
Иначе один и тот же сид даст разных людей в зависимости от порядка перебора.
Выдача навыков тоже фиксирована: `always` → родной язык школы → предметы параллели (ученик) →
лишние академические, рабочие и `adultChance` (взрослый) → черты и зажим тела → родственные
языки набора. Годовой набор добавляет только новые ключи предметов; уже выданные значения не
перебрасываются.
Ограничения — не только вниз: «атлет не может быть совсем неловким» так же осмысленно, поэтому
`min` есть наравне с `max`.
@@ -208,6 +216,13 @@
**Один набор на школу.** Выбирается в диалоге создания рядом с модами и сохраняется в файле школы.
Смеси с весами («80% славянских, 20% прочих») — не в этом срезе: они требуют UI для весов.
Набор несёт список языков, на которых здесь говорят (`nativeLanguages`). Школа выбирает **один**
при создании — это родной язык всех людей. Остальные языки списка часто появляются на низком
уровне (`relatedLanguageChance` и соседние поля на том же def): русскоязычный может понимать
белорусский. Уже выданный ключ — родной или предмет школы — не перезаписывается, поэтому
белорусский ученик сохраняет школьный русский, а не обрезанный «чуть-чуть». Шанс `0` оставляет
родственников выключенными (одноязычный пакет).
Набор имён **не связан с языком интерфейса**. Английский UI не превращает Иванову в Ivanova:
язык интерфейса — про подписи кнопок, набор имён — про то, кто учится в школе.
@@ -240,13 +255,15 @@ Protocol ← Server → Simulation → People → Content
- **Не** зависит от Arch, ASP.NET и сокетов — как `Content` сейчас.
- Отдаёт простые записи. Превращает их в сущности `World` уже `HSchool.Simulation`.
Так генератор тестируется без мира и без хоста: «этот сид + эта карта + этот набор имён → ровно
эти люди». Это единственный способ поймать регрессию в генераторе — глазами такое не проверяется.
Так генератор тестируется без мира и без хоста: «этот сид + эта карта + этот набор имён + этот
родной язык → ровно эти люди». Это единственный способ поймать регрессию в генераторе — глазами
такое не проверяется.
### Детерминизм
Генерация детерминирована от **сида**, сид лежит в файле школы. Один сид + одна карта + один набор
имён = одна и та же школа, всегда.
имён + один родной язык = одна и та же школа, всегда. Если родной язык при создании не указан,
его выбирает тот же сид — повтор без поля даёт тот же язык.
Сид у каждой семьи свой, выведенный из школьного: добавление тринадцатой семьи не должно менять
первые двенадцать. Иначе тест на генератор ломается от любой правки порядка.
@@ -268,7 +285,8 @@ Protocol ← Server → Simulation → People → Content
Школа создаётся посреди учебного года (по умолчанию 3 апреля), поэтому при создании классы уже
сформированы и возраст ученика соответствует его параллели: в N-й класс ходят те, кому
исполнилось N+6 до 1 сентября.
исполнилось N+6 до 1 сентября. Переход в следующую параллель **добавляет** навыки новых
предметов (английский с пятого, химия с восьмого) и не перебрасывает уже выданные.
## Просмотр
@@ -285,7 +303,8 @@ Protocol ← Server → Simulation → People → Content
- **Сортировки**: фамилия, возраст, параллель, должность.
- **Пейджинг** обязателен: тысяча учеников — это три тысячи человек с семьями.
- **Строка списка** — только лёгкое: ФИО, роль, класс или должность, возраст, пол.
- **Карточка** одного человека — тело, навыки, черты, нужды, семья со ссылками на родных.
- **Карточка** одного человека — тело, навыки (только те, что есть), черты, нужды, семья со
ссылками на родных.
## Масштаб
@@ -357,16 +376,18 @@ Protocol ← Server → Simulation → People → Content
| Телосложение | Производное от роста и веса, не def |
| Тело и навыки | `SkillDef.bodyLimits` зажимают навык; тело бросается первым |
| Влияние характеристик | Никакого; только просмотр |
| Навыки в `core` | Школьные предметы + физические |
| Навыки в `core` | Предметы, языки, общение, физические, рабочие |
| Выдача навыков | Не полный каталог: always, родной, предметы года, взрослые лишние, родственные языки |
| Черты в `core` | Около десяти |
| Нужды в `core` | Сон, голод, туалет, общение |
| Нужды | Машинерия есть, скорость убывания в `core` — ноль |
| Слои по ролям | Одинаковые у всех; родителей не урезаем |
| Слои по ролям | Одинаковые виды данных; ключи навыков зависят от роли и возраста |
| Набор имён | Один на школу, выбор в create, в `core` славянский; прочие — моды |
| Родной язык | Один из `nativeLanguages` набора, выбор в create; остальные языки списка — часто низкий навык |
| Падежи | Правило по умолчанию (код), явная таблица как исключение (данные) |
| Имена и язык UI | Независимы |
| Библиотека | `HSchool.People`: зависит от Content, не знает Arch и ASP.NET |
| Детерминизм | Сид в сейве, свой сид на семью |
| Детерминизм | Сид в сейве, свой сид на семью; родной язык — часть входа |
| Просмотр | Панель в оболочке менеджера, нижний ряд; не отдельный экран |
| Список | Фильтры, сортировки, пейджинг; в строке — только лёгкие поля |
| Транспорт списка | HTTP по опубликованному снимку ростера |