AltV服务器开发指南

下面给出一个示例性的（并非生产可直接使用的终极版本）基于 alt:V（Node.js 版） 的服务器端项目结构及核心代码示例，用来演示如何实现“注册登录系统、捏脸（基础角色定制）、职业系统、基本框架”等功能。此示例仅供学习参考，真正上线或部署时，你需要根据自己的需求进一步完善功能、优化安全性、编写更多业务逻辑并做好前后端的联调与测试。

---

一、项目结构示例

一个比较常见的 Node.js + alt:V 服务器目录结构如下（以“myAltVServer”项目名为例）：

text
myAltVServer
├─ package.json
├─ resource.cfg
├─ server.js                // 入口文件（Server 端代码）
├─ config
│   └─ dbConfig.js          // 数据库配置文件（示例为MySQL）
├─ modules
│   ├─ auth.js              // 注册、登录逻辑模块
│   ├─ character.js         // 角色、捏脸逻辑模块
│   ├─ jobs.js              // 职业系统逻辑模块
│   └─ utils.js             // 工具函数等
├─ client
│   ├─ client.js            // 客户端主脚本
│   ├─ ui                   // 如果使用HTML+JS做前端UI，可以放这里
│   │   ├─ index.html
│   │   └─ ...
│   └─ characterEditor.js   // 客户端：捏脸编辑逻辑
└─ .gitignore（可选）

• package.json：Node.js 依赖管理文件。
• resource.cfg：alt:V 资源配置文件，告诉 alt:V 这是一个服务端资源或客户端资源等信息。
• server.js：alt:V 服务端脚本的入口，初始化数据库、注册事件等。
• modules：根据业务功能拆分的模块化文件。
• client：客户端脚本及UI文件。

注意：这只是一个示例，实际项目可能会有更多/更少的目录拆分，也会使用更多复杂的前后端通信方案、数据库ORM等。

---

二、安装与配置

1. 安装 Node.js 依赖

先在 myAltVServer 目录下创建/编辑 package.json，并安装所需依赖（以 mysql2、bcrypt、uuid、altv-x 之类为例）：

bash
cd myAltVServer
npm init -y
npm install mysql2 bcrypt uuid

以上是最基础的例子，实际项目中可能还会使用 Sequelize / TypeORM 等 ORM ，或JWT等身份令牌机制。

2. resource.cfg

resource.cfg 告诉 alt:V 这是一个基于js的资源，示例内容如下：

cfg
type: js,
main: server.js,
client-main: client/client.js,
deps: []

• type: js：表示使用Node.js资源。
• main: server.js：服务端入口。
• client-main: client/client.js：客户端入口。

3. 数据库配置（config/dbConfig.js）

假设使用 MySQL 数据库，示例 dbConfig.js ：

js
const mysql = require('mysql2/promise');

// 数据库连接配置
const pool = mysql.createPool({
    host: 'localhost',
    user: 'root',
    password: '123456',   // 请使用真实安全的密码
    database: 'altv_game',
    connectionLimit: 10
});

module.exports = pool;

生产环境请做好数据库安全、连接池管理、异常处理等。

---

三、服务端核心逻辑示例

1. server.js（服务端入口）

js
// server.js
import alt from 'alt-server';
import * as chat from 'chat';    // alt:V内置chat包（若使用官方的chat示例）
import pool from './config/dbConfig.js';
import AuthModule from './modules/auth.js';
import CharacterModule from './modules/character.js';
import JobsModule from './modules/jobs.js';

// 初始化数据库，可以尝试建表
(async function initDatabase() {
    try {
        await pool.query(`CREATE TABLE IF NOT EXISTS users (
            id INT AUTO_INCREMENT PRIMARY KEY,
            username VARCHAR(50) UNIQUE NOT NULL,
            password VARCHAR(255) NOT NULL,
            salt VARCHAR(255),
            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
        )`);
        
        await pool.query(`CREATE TABLE IF NOT EXISTS characters (
            id INT AUTO_INCREMENT PRIMARY KEY,
            user_id INT NOT NULL,
            face_data TEXT,  -- 存储json格式的捏脸数据
            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
            FOREIGN KEY(user_id) REFERENCES users(id)
        )`);

        await pool.query(`CREATE TABLE IF NOT EXISTS jobs (
            id INT AUTO_INCREMENT PRIMARY KEY,
            user_id INT NOT NULL,
            job_name VARCHAR(50),
            level INT DEFAULT 1,
            exp INT DEFAULT 0,
            FOREIGN KEY(user_id) REFERENCES users(id)
        )`);

        alt.log('数据库初始化完成');
    } catch (err) {
        alt.logError('数据库初始化失败: ', err);
    }
})();

// 监听玩家连接
alt.on('playerConnect', (player) => {
    alt.log(`[连接事件] 玩家 ${player.name} 已连接`);
    // 通常在这里进行登录/注册UI的触发，或者引导进入登录界面
    // 这里简单示例通知客户端显示登录UI
    alt.emitClient(player, 'Client:ShowLoginUI');
});

// 处理注册
alt.onClient('Server:RequestRegister', async (player, username, password) => {
    const result = await AuthModule.register(username, password);
    if (!result.success) {
        alt.emitClient(player, 'Client:ShowNotification', result.message);
    } else {
        alt.emitClient(player, 'Client:ShowNotification', '注册成功，请登录！');
        // 也可以自动帮玩家进行登录
    }
});

// 处理登录
alt.onClient('Server:RequestLogin', async (player, username, password) => {
    const result = await AuthModule.login(username, password);
    if (!result.success) {
        alt.emitClient(player, 'Client:ShowNotification', result.message);
    } else {
        // 登录成功，把用户信息缓存到 player 自定义属性
        player.accountData = result.user;
        alt.emitClient(player, 'Client:ShowNotification', '登录成功，欢迎 ' + username);

        // 引导玩家进入捏脸界面（若玩家还没有角色）
        const hasCharacter = await CharacterModule.hasCharacter(result.user.id);
        if (!hasCharacter) {
            alt.emitClient(player, 'Client:OpenCharacterCreator');
        } else {
            // 如果已有角色，则直接加载游戏
            alt.emitClient(player, 'Client:SpawnPlayer', { x: -425.5, y: 1123.5, z: 325.9 });
        }
    }
});

// 接收捏脸数据保存
alt.onClient('Server:SaveCharacterData', async (player, faceData) => {
    if (!player.accountData) {
        alt.emitClient(player, 'Client:ShowNotification', '请先登录');
        return;
    }
    const userId = player.accountData.id;
    const result = await CharacterModule.saveCharacter(userId, faceData);
    if (result.success) {
        alt.emitClient(player, 'Client:ShowNotification', '角色创建成功');
        // 创建角色后，把玩家放到游戏出生点
        alt.emitClient(player, 'Client:SpawnPlayer', { x: -425.5, y: 1123.5, z: 325.9 });
    } else {
        alt.emitClient(player, 'Client:ShowNotification', result.message);
    }
});

// 选择职业（示例）
alt.onClient('Server:SelectJob', async (player, jobName) => {
    if (!player.accountData) {
        alt.emitClient(player, 'Client:ShowNotification', '请先登录');
        return;
    }
    const userId = player.accountData.id;
    const result = await JobsModule.chooseJob(userId, jobName);
    if (result.success) {
        alt.emitClient(player, 'Client:ShowNotification', `成功选择职业：${jobName}`);
    } else {
        alt.emitClient(player, 'Client:ShowNotification', result.message);
    }
});

// 模拟一个简单的工作经验获取
alt.onClient('Server:JobGainExp', async (player, expAmount) => {
    if (!player.accountData) {
        alt.emitClient(player, 'Client:ShowNotification', '请先登录');
        return;
    }
    const userId = player.accountData.id;
    const result = await JobsModule.gainExp(userId, expAmount);
    if (result.success) {
        alt.emitClient(player, 'Client:ShowNotification', `你获得了 ${expAmount} 点经验`);
    } else {
        alt.emitClient(player, 'Client:ShowNotification', result.message);
    }
});

上面演示了最基础的事件和逻辑调用，包括：

• playerConnect：玩家连接时发送给客户端“显示登录UI”事件。
• Server:RequestRegister：接收客户端注册请求。
• Server:RequestLogin：接收客户端登录请求。
• Server:SaveCharacterData：接收玩家提交的捏脸数据并保存。
• Server:SelectJob / Server:JobGainExp：演示一个职业系统的选择和经验获取操作。

2. modules/auth.js（注册与登录）

js
// modules/auth.js
import bcrypt from 'bcrypt';
import pool from '../config/dbConfig.js';

const AuthModule = {
    // 注册
    async register(username, password) {
        if (!username || !password) {
            return { success: false, message: '用户名或密码不能为空' };
        }

        // 检查是否已存在
        let [rows] = await pool.query('SELECT id FROM users WHERE username = ?', [username]);
        if (rows.length > 0) {
            return { success: false, message: '用户名已存在' };
        }

        try {
            const salt = await bcrypt.genSalt(10);
            const hashedPassword = await bcrypt.hash(password, salt);

            await pool.query('INSERT INTO users (username, password, salt) VALUES (?, ?, ?)', [
                username,
                hashedPassword,
                salt,
            ]);

            return { success: true, message: '注册成功' };
        } catch (err) {
            return { success: false, message: '注册失败，服务器错误' };
        }
    },

    // 登录
    async login(username, password) {
        if (!username || !password) {
            return { success: false, message: '用户名或密码不能为空' };
        }

        let [rows] = await pool.query('SELECT * FROM users WHERE username = ?', [username]);
        if (rows.length === 0) {
            return { success: false, message: '用户不存在' };
        }

        const user = rows[0];
        const match = await bcrypt.compare(password, user.password);
        if (!match) {
            return { success: false, message: '密码错误' };
        }

        // 登录成功
        return { success: true, message: '登录成功', user };
    }
};

export default AuthModule;

3. modules/character.js（角色、捏脸）

js
// modules/character.js
import pool from '../config/dbConfig.js';

const CharacterModule = {
    async hasCharacter(userId) {
        let [rows] = await pool.query('SELECT id FROM characters WHERE user_id = ?', [userId]);
        return rows.length > 0;
    },

    async saveCharacter(userId, faceData) {
        try {
            // 检查是否已经存在角色
            let [rows] = await pool.query('SELECT id FROM characters WHERE user_id = ?', [userId]);
            if (rows.length > 0) {
                // 已存在则更新
                await pool.query('UPDATE characters SET face_data = ? WHERE user_id = ?', [
                    JSON.stringify(faceData),
                    userId
                ]);
            } else {
                // 不存在则插入
                await pool.query('INSERT INTO characters (user_id, face_data) VALUES (?, ?)', [
                    userId,
                    JSON.stringify(faceData)
                ]);
            }
            return { success: true };
        } catch (error) {
            return { success: false, message: '保存角色数据失败' };
        }
    },
};

export default CharacterModule;

这里的 face_data 可以存储玩家的捏脸参数，比如 父母脸型、肤色、五官比例、发型、发色、装扮 等，这些在客户端生成或编辑完毕后通过 JSON 形式发送给服务端保存。

4. modules/jobs.js（职业系统）

js
// modules/jobs.js
import pool from '../config/dbConfig.js';

const JobsModule = {
    // 选择职业
    async chooseJob(userId, jobName) {
        // 检查是否已经有记录
        let [rows] = await pool.query('SELECT * FROM jobs WHERE user_id = ?', [userId]);
        if (rows.length > 0) {
            // 已有职业，更新或提示已经有职业
            await pool.query('UPDATE jobs SET job_name = ? WHERE user_id = ?', [jobName, userId]);
            return { success: true, message: '职业更新成功' };
        } else {
            // 插入新职业记录
            await pool.query('INSERT INTO jobs (user_id, job_name) VALUES (?, ?)', [userId, jobName]);
            return { success: true, message: '新职业选择成功' };
        }
    },

    // 增加经验
    async gainExp(userId, expAmount) {
        try {
            let [rows] = await pool.query('SELECT * FROM jobs WHERE user_id = ?', [userId]);
            if (rows.length === 0) {
                return { success: false, message: '尚未选择职业' };
            }
            const job = rows[0];
            const newExp = job.exp + expAmount;
            let newLevel = job.level;
            
            // 简单的升级判断
            if (newExp >= 100 * newLevel) {
                newLevel++;
            }
            
            await pool.query('UPDATE jobs SET exp = ?, level = ? WHERE user_id = ?', [newExp, newLevel, userId]);
            return { success: true, message: '经验增加成功', newLevel };
        } catch (error) {
            return { success: false, message: '增加经验失败' };
        }
    }
};

export default JobsModule;

---

四、客户端逻辑示例

1. client.js（客户端入口脚本）

js
// client.js
import alt from 'alt-client';
import natives from 'natives';

// 当客户端收到“Client:ShowLoginUI”事件时，显示登录UI（这里用一个简单的消息替代）
alt.onServer('Client:ShowLoginUI', () => {
    alt.log('显示登录UI...');
    // 这里可以用CEF（HTML界面）或内置绘制方法展示UI。
    // 示例：alt.showCursor(true); alt.toggleGameControls(false);
});

// 显示提示
alt.onServer('Client:ShowNotification', (msg) => {
    alt.log(`通知: ${msg}`);
    // 这里可用3D文本、原生UI或者CEF等方式实现弹窗
});

// 当客户端需要打开捏脸界面
alt.onServer('Client:OpenCharacterCreator', () => {
    alt.log('打开角色创建(捏脸)界面');
    // 这里可以加载一个页面，或者调用其它客户端脚本characterEditor.js
    // 示例： alt.emit('OpenCharacterEditorUI');
});

// 当需要将玩家出生到指定坐标
alt.onServer('Client:SpawnPlayer', (spawnPos) => {
    alt.log(`出生点: x=${spawnPos.x} y=${spawnPos.y} z=${spawnPos.z}`);
    natives.setEntityCoords(alt.Player.local.scriptID, spawnPos.x, spawnPos.y, spawnPos.z, false, false, false, true);
    // 这里还可做其他同步，比如设置模型、装备等等
});

// 示例：客户端发起注册请求
function doRegister(username, password) {
    alt.emitServer('Server:RequestRegister', username, password);
}

// 示例：客户端发起登录请求
function doLogin(username, password) {
    alt.emitServer('Server:RequestLogin', username, password);
}

// 示例：客户端发起捏脸数据保存
function saveFaceData(faceData) {
    alt.emitServer('Server:SaveCharacterData', faceData);
}

// 示例：客户端发起选择职业
function selectJob(jobName) {
    alt.emitServer('Server:SelectJob', jobName);
}

// 示例：客户端发起增加经验
function gainExp(exp) {
    alt.emitServer('Server:JobGainExp', exp);
}

// 以上函数可结合UI事件调用，例如在UI里输入账号密码后调用 doLogin/doRegister

2. characterEditor.js（示例捏脸界面脚本）

js
// characterEditor.js
import alt from 'alt-client';
import natives from 'natives';

// 这里做一个非常简化的捏脸示例
let faceData = {
    father: 0,
    mother: 0,
    resemblance: 0.5,
    skinTone: 0.5,
    // 更多参数...
};

// 调整捏脸数据
function setFaceParam(paramName, value) {
    faceData[paramName] = value;
    // 调用 natives 来实时修改玩家外观
    // 例如: natives.setPedHeadBlendData(ped, shapeFirstID, shapeSecondID, 0, skinFirstID, skinSecondID, 0, shapeMix, skinMix, 0.0, false);
}

// 当玩家点击“保存”按钮
function onSaveCharacter() {
    alt.emitServer('Server:SaveCharacterData', faceData);
}

// 仅作示例，具体如何展示UI、如何编辑五官，需要配合HTML/CEF或其它前端方案

---

五、关键点与注意事项

1. 数据库安全：

   • 尽量使用参数化查询、对密码使用强散列和盐值（如上示例的 bcrypt）。
   • 在生产环境中要配置安全的数据库连接、权限和端口。

2. 数据结构：

   • 在角色数据(characters表)里可以细化存储更多捏脸参数、外观、服装、等级、属性等。
   • 在职业数据(jobs表)里可以增加更多职业字段，如工资、职位等级、技能等。

3. 多角色支持：

   • 如果需要一个帐号下多角色，可以在 characters 表中加入 slot 或者角色名称字段等。

4. 客户端UI：

   • alt:V常见做法是使用CEF（内嵌浏览器）来制作更丰富的界面，如登录界面、角色选择界面、捏脸界面等。
   • 然后通过 alt.onServer / alt.emitServer， alt.on / alt.emit 在客户端脚本和CEF网页之间通信。

5. 地图与功能拓展：

   • 可加入地图打点(blip)、载具系统、物品背包系统、经济系统等，让游戏玩法更丰富。
   • 可借助官方的 alt:V 文档 或社区资源进一步扩展功能。

6. 测试与部署：

   • 在本地调试时，需要启动 alt:V 服务器并确认 resource.cfg 配置正确；
   • 部署到服务器时，需要开放端口、设置防火墙、保持服务器在线等。

---

六、如何启动

1. 下载并安装 alt:V 服务端，参考官方文档。
2. 在 server.cfg（alt:V根目录下）里添加你的资源：

   cfg
   resources: [
       ...
       "myAltVServer"
   ]

3. 确保 myAltVServer/resource.cfg 指向正确的入口文件：

   cfg
   type: js,
   main: server.js,
   client-main: client/client.js

4. 在 myAltVServer 目录执行 npm install，然后启动 alt:V 服务器。
5. 启动客户端并连到你服务器的IP地址进行测试。

---

总结

以上给你提供了一个最简化的示例框架，包含了：

• 注册登录（服务器+数据库+bcrypt加密）
• 捏脸（服务端保存/客户端编辑示例）
• 职业系统（服务端选择职业/升级示例）
• 基础服务端、客户端通信结构

在实际项目中，你需要针对前端UI、数据结构、安全性、玩法逻辑做更多深入的开发与优化。希望这个示例能帮助你快速上手 alt:V 服务器的基本框架与思路，祝你开发顺利!