chore: M0 项目骨架（年糕历险记）——配置/日志/主循环/数据文件/构建脚本

internal/config/config.go

@@ -0,0 +1,113 @@
+// Package config 解析 client.yaml / server.yaml 配置（设计.md §14）。
+package config
+
+import (
+	"fmt"
+	"os"
+
+	"gopkg.in/yaml.v3"
+)
+
+// ClientConfig 客户端配置（设计.md §14.2）。
+type ClientConfig struct {
+	Client struct {
+		WindowWidth    int     `yaml:"window_width"`
+		WindowHeight   int     `yaml:"window_height"`
+		WindowTitle    string  `yaml:"window_title"`
+		VSync          bool    `yaml:"vsync"`
+		FOV            float64 `yaml:"fov"`
+		RenderDistance int     `yaml:"render_distance"`
+		Language       string  `yaml:"language"`
+		Graphics       struct {
+			SmoothLighting bool `yaml:"smooth_lighting"`
+			Mipmap         bool `yaml:"mipmap"`
+			Anisotropic    int  `yaml:"anisotropic"`
+		} `yaml:"graphics"`
+		Audio struct {
+			Volume float64 `yaml:"volume"`
+			Music  bool    `yaml:"music"`
+		} `yaml:"audio"`
+	} `yaml:"client"`
+}
+
+// DefaultClient 客户端默认配置。
+func DefaultClient() *ClientConfig {
+	c := &ClientConfig{}
+	c.Client.WindowWidth = 1280
+	c.Client.WindowHeight = 720
+	c.Client.WindowTitle = "年糕历险记"
+	c.Client.VSync = true
+	c.Client.FOV = 70
+	c.Client.RenderDistance = 12
+	c.Client.Language = "zh_cn"
+	c.Client.Graphics.SmoothLighting = true
+	c.Client.Graphics.Mipmap = true
+	c.Client.Graphics.Anisotropic = 4
+	c.Client.Audio.Volume = 1.0
+	c.Client.Audio.Music = true
+	return c
+}
+
+// ServerConfig 服务器配置（设计.md §14.1）。
+type ServerConfig struct {
+	Server struct {
+		Port         int `yaml:"port"`
+		MaxPlayers   int `yaml:"max_players"`
+		ViewDistance int `yaml:"view_distance"`
+		TickRate     int `yaml:"tick_rate"`
+	} `yaml:"server"`
+	World struct {
+		Seed      int64  `yaml:"seed"`
+		Name      string `yaml:"name"`
+		Generator struct {
+			BiomeScale  float64 `yaml:"biome_scale"`
+			HeightScale float64 `yaml:"height_scale"`
+			CaveDensity float64 `yaml:"cave_density"`
+		} `yaml:"generator"`
+	} `yaml:"world"`
+	Mods struct {
+		Enabled         bool   `yaml:"enabled"`
+		Directory       string `yaml:"directory"`
+		AllowScripts    bool   `yaml:"allow_scripts"`
+		ScriptTimeoutMS int    `yaml:"script_timeout_ms"`
+		HotReload       bool   `yaml:"hot_reload"`
+	} `yaml:"mods"`
+}
+
+// DefaultServer 服务器默认配置。
+func DefaultServer() *ServerConfig {
+	c := &ServerConfig{}
+	c.Server.Port = 25565
+	c.Server.MaxPlayers = 20
+	c.Server.ViewDistance = 10
+	c.Server.TickRate = 20
+	c.World.Seed = 123456789
+	c.World.Name = "NewWorld"
+	c.World.Generator.BiomeScale = 0.005
+	c.World.Generator.HeightScale = 0.01
+	c.World.Generator.CaveDensity = 0.1
+	c.Mods.Enabled = true
+	c.Mods.Directory = "mods"
+	c.Mods.AllowScripts = true
+	c.Mods.ScriptTimeoutMS = 5
+	return c
+}
+
+// Load 读取 YAML 配置；文件不存在时返回 defaults（零拷贝不可行则回退默认构造）。
+func Load[T any](path string, defaults *T) (*T, error) {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return defaults, nil
+		}
+		return nil, fmt.Errorf("config.Load %s: %w", path, err)
+	}
+	out := new(T)
+	if defaults != nil {
+		*out = *defaults
+	}
+	if err := yaml.Unmarshal(b, out); err != nil {
+		return nil, fmt.Errorf("config.Load %s: %w", path, err)
+	}
+	return out, nil
+}

internal/engine/loop.go

@@ -0,0 +1,55 @@
+// Package engine 主循环：tick 固定 20Hz、render 吃满帧率、两者解耦（架构.md §3.2）。
+package engine
+
+import (
+	"context"
+	"time"
+)
+
+// Ticker 世界逻辑接口：每 tick 调用，dt 为固定 tick 间隔秒数。
+type Ticker interface {
+	Tick(dt float64)
+}
+
+// Renderer 渲染接口：每帧调用；ShouldClose 返回 true 时退出循环。
+type Renderer interface {
+	Render()
+	ShouldClose() bool
+}
+
+// NoopRenderer 无渲染占位（服务器），以约 60Hz 空转。
+type NoopRenderer struct{}
+
+// Render 空实现。
+func (NoopRenderer) Render() { time.Sleep(time.Second / 60) }
+
+// ShouldClose 永不主动关闭。
+func (NoopRenderer) ShouldClose() bool { return false }
+
+// Run 主循环：tick goroutine 固定 20Hz；主 goroutine 渲染；ctx 取消或窗口关闭时退出。
+func Run(ctx context.Context, tick Ticker, render Renderer) {
+	const tickInterval = time.Second / 20
+	stop := make(chan struct{})
+	go func() {
+		t := time.NewTicker(tickInterval)
+		defer t.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-stop:
+				return
+			case <-t.C:
+				tick.Tick(tickInterval.Seconds())
+			}
+		}
+	}()
+	defer close(stop)
+
+	for {
+		if ctx.Err() != nil || render.ShouldClose() {
+			return
+		}
+		render.Render()
+	}
+}

internal/logx/log.go

@@ -0,0 +1,81 @@
+// Package logx 分级日志（debug/info/warn/error），输出 stderr 与可选文件。
+package logx
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"sync"
+	"time"
+)
+
+// Level 日志级别。
+type Level int
+
+const (
+	// LevelDebug 调试。
+	LevelDebug Level = iota
+	// LevelInfo 常规信息。
+	LevelInfo
+	// LevelWarn 警告。
+	LevelWarn
+	// LevelError 错误。
+	LevelError
+)
+
+// Logger 线程安全分级日志器。
+type Logger struct {
+	mu    sync.Mutex
+	level Level
+	w     io.Writer
+}
+
+// New 创建日志器；file 为空仅输出 stderr。
+func New(file string, level Level) (*Logger, error) {
+	w := io.Writer(os.Stderr)
+	if file != "" {
+		if err := os.MkdirAll(pathDir(file), 0o755); err != nil {
+			return nil, fmt.Errorf("logx.New mkdir: %w", err)
+		}
+		f, err := os.OpenFile(file, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o644)
+		if err != nil {
+			return nil, fmt.Errorf("logx.New %s: %w", file, err)
+		}
+		w = io.MultiWriter(os.Stderr, f)
+	}
+	return &Logger{level: level, w: w}, nil
+}
+
+// pathDir 返回路径的目录部分（"a.log" → "."）。
+func pathDir(p string) string {
+	for i := len(p) - 1; i >= 0; i-- {
+		if p[i] == '/' || p[i] == '\\' {
+			if i == 0 {
+				return p[:1]
+			}
+			return p[:i]
+		}
+	}
+	return "."
+}
+
+func (l *Logger) logf(lv Level, tag, format string, args ...any) {
+	if lv < l.level {
+		return
+	}
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	fmt.Fprintf(l.w, "[%s] [%s] %s\n", time.Now().Format("15:04:05.000"), tag, fmt.Sprintf(format, args...))
+}
+
+// Debugf 调试输出。
+func (l *Logger) Debugf(format string, args ...any) { l.logf(LevelDebug, "DEBUG", format, args...) }
+
+// Infof 常规输出。
+func (l *Logger) Infof(format string, args ...any) { l.logf(LevelInfo, "INFO", format, args...) }
+
+// Warnf 警告输出。
+func (l *Logger) Warnf(format string, args ...any) { l.logf(LevelWarn, "WARN", format, args...) }
+
+// Errorf 错误输出。
+func (l *Logger) Errorf(format string, args ...any) { l.logf(LevelError, "ERROR", format, args...) }