# Repository Guidelines

## Project Structure & Module Organization
This repository is split into multiple Go modules:

- `logic/`: main game logic and fight system (`logic/service/fight/...`)
- `login/`: login service
- `common/`: shared utilities, data, RPC helpers, socket code
- `modules/`: domain modules such as `player`, `task`, `space`
- `public/`: runtime data and configs, including `public/config/*.json`
- `docs/`: engineering notes and feature-specific summaries

Keep changes scoped to the owning module. For example, fight effect work belongs under `logic/service/fight/effect/`.

## Build, Test, and Development Commands
- `cd logic && go test ./service/fight/effect`
  Validates effect package changes quickly.
- `cd logic && go test ./...`
  Runs all tests in the `logic` module.
- `cd common && go test ./...`
  Runs shared utility tests.
- `cd logic && go build ./...`
  Checks compile health for the logic module.

CI currently builds Go artifacts through GitHub Actions in `.github/workflows/logic_CI.yml`.

## Coding Style & Naming Conventions
Use standard Go formatting and idioms:

- Run `gofmt -w <file>.go` on edited Go files.
- Use tabs as produced by `gofmt`; do not hand-align spacing.
- Keep package names lowercase.
- Follow existing effect naming: `Effect<ID>` structs in files like `effect_123.go` or grouped files such as `400_480_...go`.
- Keep comments short and descriptive, e.g. `// Effect 400: 若和对手属性相同，则技能威力翻倍`.

## Testing Guidelines
The repo uses Go’s built-in `testing` package. Existing tests are sparse, so at minimum:

- run package-level tests for the module you changed
- prefer targeted verification first, then broader `go test ./...` when practical
- name tests with Go conventions, e.g. `TestSqrt`, `TestEffect400`

If no automated test exists, document the package-level command you used to validate the change.

## Commit & Pull Request Guidelines
Recent history is inconsistent (`fix: ...`, `编辑文件 ...`, and short placeholder commits). Prefer clear messages:

- `fix: correct Effect599 damage reduction category handling`
- `docs: update effect refactor summary`

For pull requests, include:

- what changed
- affected module(s)
- validation commands run
- linked issue/task if available

## Contributor Notes
Do not overwrite unrelated local changes. This repo often has a dirty worktree. Prefer additive edits, and update `docs/` when continuing long-running refactors such as fight effects.

## Battle System Notes
Most combat work lives under `logic/service/fight/`. Use the existing split before adding code:

- `action/`: battle action types and turn execution helpers
- `input/`: runtime battle state, effect registration, skill parsing
- `info/`: core battle entities such as pets, skills, damage zones, enums
- `effect/`: skill effects and status logic; most day-to-day fight changes land here
- `node/`: shared effect node behavior and default hooks
- `boss/`: boss-only passive/index effects
- `rule/`, `itemover/`, `top/`: rules, item settlement, ranking-related battle logic

When adding a new skill effect:

- prefer `logic/service/fight/effect/`
- follow existing naming such as `Effect400` or grouped files like `400_480_...go`
- register via `input.InitEffect(...)` or existing helper registration paths
- update `effect_info_map.go` if the effect should appear in local effect descriptions

When investigating missing effects, do not rely only on direct `InitEffect(...)` grep results. This repo also uses shared registration files such as:

- `sterStatusEffects.go`
- `effect_power_doblue.go`
- `EffectAttackMiss.go`
- `EffectPhysicalAttackAddStatus.go`
- `EffectDefeatTrigger.go`
- `effect_attr.go`

Recommended validation for fight changes:

- `cd logic && go test ./service/fight/effect`
- `cd logic && go build ./...`

If you continue long-running effect work, update the matching summary in `docs/` so the next pass can resume without re-scanning the whole package.