amxmodx-basics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AMX Mod X (Pawn) Code Style Guide

AMX Mod X (Pawn) 代码风格指南

This document provides an overview of coding conventions for AMX Mod X projects. Each topic is covered in detail in its own file.

本文档概述了AMX Mod X项目的编码规范，每个主题的详细内容都在独立文件中。

Core Conventions

核心规范

Category	Description
Basics	Syntax, basics
Code Style	File structure, formatting, braces, spacing, plugin registration
Naming Conventions	Hungarian notation, variable prefixes, naming patterns
Constants & Enums	Define constants, enums, TASKID constants
Macros	Common macros, IS_PLAYER, patterns to avoid
Function Declarations	Return types, @ prefix, static variables
Validations	FM_NULLENT, entity checks, player validation, early returns

分类	描述
基础	语法、基础知识
代码风格	文件结构、格式、大括号、间距、插件注册
命名规范	匈牙利命名法、变量前缀、命名模式
常量与枚举	定义常量、枚举、TASKID常量
宏	常用宏、IS_PLAYER、需避免的模式
函数声明	返回类型、@前缀、静态变量
验证	FM_NULLENT、实体检查、玩家验证、提前返回

API Patterns

API模式

Category	Description
Hooks	Ham, FakeMeta, ReAPI, Event, Message hooks and handles
Forwards	CreateMultiForward, ExecuteForward, pre/post patterns
Natives	Native registration and implementation
Callbacks	Tasks, SQL queries, CVar queries
Menus	Menu creation, callbacks, and patterns
Commands	Client, server, and console commands
CVars	CVar creation, binding, and change hooks

分类	描述
钩子	Ham、FakeMeta、ReAPI、事件、消息钩子及句柄
转发	CreateMultiForward、ExecuteForward、前置/后置模式
原生函数	原生函数注册与实现
回调	任务、SQL查询、CVar查询
菜单	菜单创建、回调及模式
命令	客户端、服务器及控制台命令
CVar	CVar创建、绑定及变更钩子

Performance & Data

性能与数据

Category	Description
Optimizations	Native call reduction, dynamic hooks, model path caching
Data Structures	Arrays, Tries, entity access, strings

分类	描述
优化	减少原生函数调用、动态钩子、模型路径缓存
数据结构	数组、Trie、实体访问、字符串

Custom API Reference

自定义API参考

For project-specific APIs, see dedicated skill files:

API	Description
assets	Asset management from JSON configs
custom-entities	OOP-style custom entities
custom-events	Pub/sub event system
custom-weapons	Custom weapon framework
entity-force	Physics force application
entity-grab	Entity grab and carry
player-camera	Custom camera views
player-model	Custom player models
player-music	MP3 music playback
player-roles	Player role management
rounds	Round management
shops	In-game shop system
states	State machine implementation

For large project organization with namespace constants, see amxx-modding-kit-project.

针对项目特定API，请查看专用技能文件：

API	描述
assets	基于JSON配置的资源管理
custom-entities	面向对象风格的自定义实体
custom-events	发布/订阅事件系统
custom-weapons	自定义武器框架
entity-force	物理力施加
entity-grab	实体抓取与携带
player-camera	自定义相机视角
player-model	自定义玩家模型
player-music	MP3音乐播放
player-roles	玩家角色管理
rounds	回合管理
shops	游戏内商店系统
states	状态机实现

如需使用命名空间常量进行大型项目组织，请查看amxx-modding-kit-project。

Quick Reference: Best Practices Summary

快速参考：最佳实践摘要

Code Style

代码风格

Always use
```
#pragma semicolon 1
```
at file start
Use Hungarian notation for all variable names
Use K&R brace style (opening brace on same line)
Pass plugin info directly to
```
register_plugin()
```
- avoid macros
Group hooks and functions with section comments

始终在文件开头使用
```
#pragma semicolon 1
```
所有变量名使用匈牙利命名法
使用K&R大括号风格（左大括号与代码同行）
直接将插件信息传入
```
register_plugin()
```
- 避免使用宏
使用分段注释对钩子和函数进行分组

Constants & Validation

常量与验证

Use
```
FM_NULLENT
```
instead of
```
-1
```
or
```
0
```
for null entity checks
Always check
```
FM_NULLENT
```
after entity creation before processing
Return
```
FM_NULLENT
```
not
```
0
```
for failures -
```
0
```
is worldspawn
Return early for invalid conditions

检查空实体时，使用
```
FM_NULLENT
```
而非
```
-1
```
或
```
0
```
实体创建后，在处理前务必检查
```
FM_NULLENT
```
失败时返回
```
FM_NULLENT
```
而非
```
0
```
-
```
0
```
代表worldspawn（世界实体）
遇到无效条件时提前返回

Macros

宏

Don't redefine macros - use shared definitions from includes
Never use
```
MACRO()_Suffix
```
patterns in code - only in macro definitions

不要重定义宏 - 使用头文件中的共享定义
代码中绝不要使用
```
MACRO()_Suffix
```
模式 - 仅在宏定义中使用

Function Declarations

函数声明

Use
```
@
```
prefix only for OOP-like methods:
```
@{EntityName}_{MethodName}
```
Never add
```
public
```
keyword to
```
@
```
prefixed functions
Use
```
const
```
prefix for all handle arguments
Use
```
const &this
```
for "this" argument in OOP-like methods
Use static variables in frequently called class methods
Declare and assign static on same line using semicolon separator

仅在类对象风格的方法中使用
```
@
```
前缀：
```
@{EntityName}_{MethodName}
```
带
```
@
```
前缀的函数绝不要添加
```
public
```
关键字
所有句柄参数使用
```
const
```
前缀
类对象风格的方法中，为“this”参数使用
```
const &this
```
频繁调用的类方法中使用静态变量
静态变量的声明与赋值在同一行，使用分号分隔

Hooks

钩子

Ham hooks must return
```
HAM_*
```
constants
FakeMeta hooks must return
```
FMRES_*
```
constants
ReAPI hooks must return
```
HC_*
```
constants
Message hooks must return
```
PLUGIN_*
```
constants
Hook handle variables:
```
g_pfwham
```
(Ham),
```
g_pfwfm
```
(FakeMeta)
Inline
```
get_user_msgid
```
when only used once in
```
register_message
```

Ham钩子必须返回
```
HAM_*
```
常量
FakeMeta钩子必须返回
```
FMRES_*
```
常量
ReAPI钩子必须返回
```
HC_*
```
常量
消息钩子必须返回
```
PLUGIN_*
```
常量
钩子句柄变量：
```
g_pfwham
```
（Ham）、
```
g_pfwfm
```
（FakeMeta）
若
```
get_user_msgid
```
仅在
```
register_message
```
中使用一次，则内联调用

Forwards

Forward names use
```
LibraryName_OnSomething
```
- not
```
Fw_
```
prefix
Multi-forward handle variables use
```
g_pfw
```
prefix

转发名称使用
```
LibraryName_OnSomething
```
格式 - 不要使用
```
Fw_
```
前缀
多转发句柄变量使用
```
g_pfw
```
前缀

Natives & Callbacks

原生函数与回调

Native implementations use
```
Native_
```
prefix with
```
const
```
for arguments
Task callbacks use
```
Task_
```
prefix with offset in task ID
SQL callbacks use
```
Callback_SQLQuery_{Name}
```
prefix

原生函数实现使用
```
Native_
```
前缀，参数使用
```
const
```
任务回调使用
```
Task_
```
前缀，任务ID中包含偏移量
SQL回调使用
```
Callback_SQLQuery_{Name}
```
前缀

Menus

菜单

Menu callbacks use
```
Callback_Menu_{Name}
```
prefix
Use enum for menu items to avoid index mistakes
Destroy dynamic menus in callback with
```
menu_destroy
```

菜单回调使用
```
Callback_Menu_{Name}
```
前缀
使用枚举定义菜单项，避免索引错误
在回调中使用
```
menu_destroy
```
销毁动态菜单

Commands & CVars

命令与CVar

Command handlers use
```
Command_
```
prefix, server commands use
```
ServerCommand_
```
Use
```
register_concmd
```
for admin commands that should work from RCON
Avoid
```
client_cmd
```
- use
```
engclient_cmd
```
for server-side execution
Use
```
create_cvar
```
instead of deprecated
```
register_cvar
```
Use
```
bind_pcvar_*
```
instead of
```
get_pcvar_*
```
for cvar access

命令处理函数使用
```
Command_
```
前缀，服务器命令使用
```
ServerCommand_
```
前缀
对于可通过RCON执行的管理员命令，使用
```
register_concmd
```
避免使用
```
client_cmd
```
- 服务器端执行时使用
```
engclient_cmd
```
使用
```
create_cvar
```
替代已废弃的
```
register_cvar
```
访问CVar时使用
```
bind_pcvar_*
```
而非
```
get_pcvar_*
```

Optimizations

优化

Minimize native calls in hot paths
Use single global
```
g_pTrace
```
- never create trace handles per-call
Register high-frequency hooks dynamically
Use
```
xs_vec_set
```
instead of
```
xs_vec_copy
```
for vector initialization
Cache model index with static inside function, not in separate global

在热点路径中尽量减少原生函数调用
使用单个全局
```
g_pTrace
```
- 绝不要每次调用都创建追踪句柄
动态注册高频钩子
初始化向量时使用
```
xs_vec_set
```
而非
```
xs_vec_copy
```
在函数内部使用静态变量缓存模型索引，而非单独的全局变量

Naming Conventions

命名规范

Sound arrays use
```
g_rgsz
```
prefix with
```
g_i*Num
```
counter
Message IDs use
```
gmsg
```
prefix (without underscore)
Player arrays use
```
g_rg*[MAX_PLAYERS + 1]
```
with type prefix
Don't use
```
id
```
for players - use
```
pPlayer
```
Don't use
```
index
```
for entities - use
```
pEntity
```

声音数组使用
```
g_rgsz
```
前缀，搭配
```
g_i*Num
```
计数器
消息ID使用
```
gmsg
```
前缀（无下划线）
玩家数组使用
```
g_rg*[MAX_PLAYERS + 1]
```
格式，带类型前缀
不要用
```
id
```
指代玩家 - 使用
```
pPlayer
```
不要用
```
index
```
指代实体 - 使用
```
pEntity
```

Data Structures

数据结构

Always free dynamic handles -
```
ArrayDestroy
```
,
```
TrieDestroy
```
in
```
plugin_end()
```

务必释放动态句柄 - 在
```
plugin_end()
```
中调用
```
ArrayDestroy
```
、
```
TrieDestroy
```