이 가이드는 Legion Hosting의 alt:V 서버를 위한 리소스 개발, 데이터베이스 설정, 관리자 도구, 플레이어 관리, 차량 및 무기 관리, 문제 해결을 다룹니다. 초기 서버 설정, server.toml 구성 및 연결 방법에 대해서는 alt:V 서버 설정 가이드를 참조하세요.
관리자 설정
alt:V에는 내장 관리자 시스템이 없습니다. 관리자 기능은 직접 만들거나 설치하는 리소스(스크립트)를 통해 구현됩니다. 대부분의 게임모드는 권한 레벨, 역할, 관리자 명령어가 있는 자체 관리자 시스템을 구현합니다.
일반적인 관리자 접근 방식
- 데이터베이스 기반 역할: 대부분의 롤플레이 및 게임모드 프레임워크는 관리자 역할을 데이터베이스에 저장합니다. 관리자는 서로 다른 권한 레벨을 부여하는 역할(예: 모더레이터, 관리자, 슈퍼관리자)을 배정받습니다.
- 구성 기반 관리자: 더 간단한 설정에서는 관리자 Steam ID나 alt:V ID와 그 권한 레벨을 나열하는 구성 파일을 사용할 수 있습니다.
- 콘솔 명령어: GPanel 서버 콘솔은 항상 전체 접근 권한을 가집니다. 관리자 작업을 위해 콘솔 입력을 받는 서버 측 스크립트를 작성할 수 있습니다.
관리자 리소스 설정
- 게임모드에 맞는 관리자 리소스를 선택하거나 개발합니다.
- Files 탭이나 SFTP를 통해 리소스를
resources/디렉터리에 업로드합니다. server.toml의resources배열에 리소스 이름을 추가합니다.- 관리자 리소스를 구성합니다(관리자 Steam/alt:V ID, 권한 레벨 등 설정).
- 서버를 재시작합니다.
리소스 시스템
리소스는 alt:V 서버의 핵심 구성 요소입니다. 각 리소스는 서버 측 코드, 클라이언트 측 코드 또는 둘 다를 포함할 수 있는 독립적인 모듈입니다. 리소스는 JavaScript, TypeScript 또는 C#으로 작성됩니다.
리소스 구조
resources/
my-resource/
resource.toml <-- Resource configuration (required)
server/
index.js <-- Server-side entry point
utils.js <-- Additional server-side files
client/
index.js <-- Client-side entry point (runs in player's GTA V)
shared/
config.js <-- Shared code accessible by both server and clientresource.toml 구성
type = "js"
main = "server/index.js"
client-main = "client/index.js"
client-files = ["client/*"]
deps = ["chat"]필드: type (js 또는 csharp), main (서버 측 진입점), client-main (클라이언트 측 진입점, 플레이어의 GTA V에서 실행), client-files (클라이언트로 전송할 파일, 글로브 지원), deps (먼저 로드할 다른 리소스).
리소스 설치
서버에 미리 제작된 리소스를 설치하려면:
- 리소스 파일(일반적으로
resource.toml과 스크립트 파일을 포함하는 폴더)을 다운로드합니다. - GPanel에서 서버를 중지합니다.
- Files 탭이나 SFTP를 통해 리소스 폴더를
resources/에 업로드합니다. server.toml의resources배열에 리소스 폴더 이름을 추가합니다:
resources = ["existing-resource", "new-resource"]- 리소스에 종속성이 있는 경우, 해당 종속성도 설치되고 나열되어 있는지 확인합니다.
- 문서에 따라 리소스를 구성합니다(구성 파일, 데이터베이스 설정 등).
- 서버를 시작합니다. 콘솔에서 리소스 로딩 메시지와 오류가 있는지 확인합니다.
리소스 제거
- 서버를 중지합니다.
server.toml의resources배열에서 리소스 이름을 제거합니다.- 선택적으로
resources/에서 리소스 폴더를 삭제합니다. - 서버를 시작합니다.
deps 필드를 확인하세요.
데이터베이스 설정
대부분의 alt:V 게임모드는 플레이어 데이터, 차량, 인벤토리 및 기타 영구 정보를 저장하기 위해 데이터베이스가 필요합니다. alt:V에서 가장 일반적인 두 가지 데이터베이스 시스템은 MongoDB와 MySQL/MariaDB입니다.
MongoDB
MongoDB는 JavaScript/TypeScript 리소스와 함께 일반적으로 사용되는 NoSQL 문서 데이터베이스입니다. MongoDB Atlas(무료 등급 사용 가능)와 같은 관리형 서비스나 자체 호스팅 인스턴스를 사용하세요. 연결 문자열(예: mongodb+srv://user:[email protected]/mydb)을 가져와 리소스의 구성 파일에 설정합니다. Node.js 리소스는 mongodb npm 패키지를 사용합니다.
MySQL / MariaDB
MySQL은 C# 리소스 및 일부 JavaScript 프레임워크와 함께 일반적으로 사용됩니다. 관리형 서비스나 자체 호스팅 인스턴스에서 데이터베이스를 얻고, 연결 세부 정보(호스트, 포트, 사용자 이름, 비밀번호, 데이터베이스 이름)로 리소스를 구성하고, 필요한 SQL 마이그레이션 스크립트를 실행하세요.
플레이어 관리
alt:V의 플레이어 관리는 리소스를 통해 처리됩니다. 일반적인 작업은 다음과 같습니다:
플레이어 식별
alt:V는 연결된 각 플레이어에 대해 여러 식별자를 제공합니다:
| 식별자 | 설명 |
|---|---|
player.id |
현재 세션에 할당된 임시 숫자 ID. 재연결 시 변경됩니다. |
player.socialID |
플레이어의 Rockstar Social Club ID. 세션 간에 유지됩니다. |
player.hwidHash |
하드웨어 식별자 해시. 차단 적용에 유용합니다. |
player.ip |
플레이어의 IP 주소. |
강퇴 및 차단
리소스에서 강퇴 및 차단 기능을 구현하세요:
import alt from "alt-server";
// Kick a player
player.kick("Reason for kick");
// Ban check on connect (store bans in database)
alt.on("playerConnect", (player) => {
if (isPlayerBanned(player.socialID)) {
player.kick("You are banned from this server.");
}
});socialID와 hwidHash를 사용하세요.
차량 및 무기 관리
차량과 무기는 서버 측 스크립트를 통해 관리됩니다. alt:V는 차량과 무기의 스폰, 수정, 제거에 대한 완전한 제어 권한을 제공합니다.
차량 스폰
import alt from "alt-server";
// Spawn a vehicle at a position
const vehicle = new alt.Vehicle(
"sultan", // Vehicle model name
0, 0, 72, // Position (x, y, z)
0, 0, 0 // Rotation (rx, ry, rz)
);
vehicle.numberPlateText = "LEGION";무기 지급
// Give a weapon to a player
player.giveWeapon(alt.hash("weapon_pistol"), 100, true);
// Remove all weapons
player.removeAllWeapons();차량 영속성
기본적으로 차량은 서버 메모리에만 존재하며 재시작 시 손실됩니다. 재시작 간에 차량을 유지하려면 차량 데이터(모델, 위치, 수정 사항, 소유자)를 데이터베이스에 저장하고 서버 시작 시 다시 생성하세요.
문제 해결
리소스가 로드되지 않음
server.toml의 리소스 이름이resources/의 폴더 이름과 정확히 일치하는지 확인하세요.- 리소스에 올바른
type과main필드가 있는 유효한resource.toml파일이 있는지 확인하세요. - 리소스 로딩 중 콘솔에서 오류 메시지를 확인하세요. 스크립트의 구문 오류는 리소스 시작을 방해합니다.
deps에 나열된 모든 종속성이 설치되고 로드되었는지 확인하세요.server.toml에 올바른 모듈이 로드되어 있는지 확인하세요(JavaScript는js-module, C#은csharp-module).
플레이어가 연결할 수 없음
- 서버가 실행 중이고 GPanel에서 온라인으로 표시되는지 확인하세요.
- 플레이어가 일반 GTA V 런처가 아닌 alt:V 런처를 사용하고 있는지 확인하세요.
- alt:V 서버 브랜치가 플레이어가 가진 것(release, rc 또는 dev)과 일치하는지 확인하세요. 브랜치가 일치하지 않으면 연결이 차단됩니다.
- 비밀번호로 보호된 경우, 플레이어가 올바른 비밀번호를 입력하고 있는지 확인하세요.
- 플레이어가 IP와 포트로 직접 연결을 시도하도록 하세요. 서버 IP 및 포트 찾는 방법을 참조하세요.
서버 충돌
- 충돌 전에 콘솔에서 오류 메시지를 확인하세요.
- 결함이 있는 리소스가 충돌의 가장 흔한 원인입니다. 최근에 추가한 리소스를 비활성화하여 문제를 분리하세요.
- 서버 파일이 최신 상태인지 확인하세요. 필요한 경우 Startup 탭에서 재설치를 실행하세요.
- 리소스의 메모리 누수는 시간이 지남에 따라 서버의 RAM을 소진시킬 수 있습니다. 메모리 사용량이 꾸준히 증가하는지 GPanel 리소스 그래프를 모니터링하세요.
데이터베이스 및 음성 문제
- 데이터베이스 자격 증명과 연결 문자열을 확인하세요. MongoDB Atlas의 경우, 네트워크 접근 설정에서 서버의 IP를 허용 목록에 추가하세요.
- 콘솔에서 데이터베이스 연결 오류 메시지를 확인하세요.
- 음성 채팅에는
server.toml의[voice]섹션과 음성 채널 로직을 구현하는 리소스가 필요합니다. 구성만으로는 인프라만 설정됩니다.
성능 문제
- 비용이 큰 작업(무거운 루프, 동기 데이터베이스 호출, 과도한 엔티티 생성)에 대해 리소스를 프로파일링하세요.
alt.setInterval과alt.setTimeout을 신중하게 사용하세요. 틱마다 수행되는 무거운 작업이 가장 흔한 성능 저하 원인입니다.- CPU 및 RAM 사용량에 대해 GPanel 리소스 그래프를 모니터링하세요.
- 높은 플레이어 수의 경우 서버 플랜 업그레이드를 고려하세요. 옵션을 논의하려면 지원 티켓을 열어주세요.
관련 문서
- alt:V 서버 설정 가이드 — 초기 설정, server.toml 구성, 음성 채팅 및 연결 방법
- 서버 IP 및 포트 찾는 방법
- SFTP를 통한 파일 업로드 방법
- 서버 시작 가이드 — Legion Hosting에서 모든 게임 서버를 시작하기 위한 일반 가이드
추가 도움이 필요하신가요?
이 가이드에서 다루지 않은 문제를 겪고 계시다면, 저희 지원팀이 도와드릴 준비가 되어 있습니다. legionhosting.net/submitticket.php에서 서버 세부 정보, 문제 설명 및 GPanel 콘솔의 관련 오류 메시지와 함께 티켓을 열어주세요.
