mLua · Nemotron-CC 리프레이즈 (CPT)

[task] | knowledge_list [title] | MSW 기본 이벤트 함수 [category] | Guides [rephrased] | ```lua -- OnUpdate -- [server only] 또는 [client only] 또는 [server] 또는 [client] 또는 [multicast] (구체적 실행 공간 명시 없음, 일반적 Update는 서버/클라이언트 모두 가능하나 문서에서 명시되지 않음) -- 매개변수: number delta (이전 프레임에 걸린 시간 값, 단위: 초) -- 반환 타입: void -- 설명: OnBeginPlay 함수 호출 이후, 프레임마다 호출되는 함수입니다. -- 프레임별로 엔티티 위치, 상태, 동작을 변경하고 싶다면 OnUp [original] | `OnBeginPlay` 함수 호출 이후, 프레임마다 호출되는 함수입니다. 따라서 프레임별로 엔티티 위치, 상태, 동작을 변경하고 싶다면 `OnUpdate` 함수에 스크립트를 작성합니다. 매개 변수로 **delta**를 사용하며, 이전 프레임에 걸린 시간 값(단위: 초)을 받습니다. **delta**를 활용하여 프레임 단위 구현을 할 수 있고, 특정 시간마다 액션을 제어할 수 있습니다. ```lua void OnUpdate(number delta) { if self._T.Time == nil then self._T.Time [chunk_id] | Guides:163:2

[task] | extract_knowledge [title] | Maple GYM 만들기 Ⅱ [category] | Guides [rephrased] | # GYM 정보 UI 갱신 로직 구현 본 절에서는 `Maple GYM` 시스템에서 플레이어의 현재 등급(스킬, DNA)과 보유 금액을 바탕으로 상점 버튼의 텍스트와 색상을 동적으로 갱신하는 `SetShopInfo()` 메서드의 구현 방식을 다룹니다. ## 1. 개념 설명 `SetShopInfo()` 메서드는 플레이어의 상태 데이터(`self.Stats`)를 읽어 다음 세 가지 정보를 계산합니다. 1. **현재 등급 확인**: `CurrentSkillGrade`, `CurrentDnaGrade` 값을 정수로 변환하여 현재 위치를 [original] | ```lua void SetShopInfo() { local skillGrade = math.floor(self.Stats.CurrentSkillGrade) local dnaGrade = math.floor(self.Stats.CurrentDnaGrade) self.SkillLevelText.Text = ("기술 레벨: "..skillGrade.."레벨") self.DnaLevelText.Text = ("DNA: "..self.Stats.DnaG [chunk_id] | Guides:143:5

[task] | knowledge_list [title] | 엔티티와 컴포넌트 참조 [category] | Guides [rephrased] | 제공된 문서 내용에만 기반하여 추출한 핵심 사실 목록입니다. 1. 엔티티는 서로 다른 컴포넌트로 구성되며, 엔티티 간에는 상위(Parent)와 하위(Child) 관계로 연결되어 있어 특정 컴포넌트에서 다른 엔티티나 컴포넌트로 접근할 수 있는 구조를 가집니다. 2. 스크립트 컴포넌트 내에서 자기 자신을 포함하는 엔티티에 접근하기 위해 `self.Entity` 속성을 사용하며, 이 속성은 해당 컴포넌트가 장착된 `Entity` 객체를 반환합니다. 3. `self.Entity`를 통해 참조한 엔티티의 이름을 출력하려면 `Entity.N [original] | # 학습 과정 소개 엔티티와 컴포넌트 구조를 간략하게 이해하고, 스크립트를 통해 엔티티와 컴포넌트에 접근하는 방법을 알아봅니다. # 엔티티와 컴포넌트 구조 먼저 엔티티와 컴포넌트의 구조를 알아보겠습니다. 기본적으로 엔티티는 각기 다른 컴포넌트들로 구성되어 있고, 각각의 엔티티는 상위, 하위 관계로 연결되어 있습니다. 이 연결 구조를 이용하면 특정 컴포넌트에서 다른 엔티티나 컴포넌트로 접근할 수 있습니다. 아래 이미지는 엔티티 간의 상-하위 구조와 각 엔티티를 구성하는 컴포넌트를 도식화한 것입니다. 이후 이 구조를 바탕으로 설명 [chunk_id] | Guides:164:0

[task] | diverse_qa [title] | MSW 기본 이벤트 함수 [category] | Guides [rephrased] | 질문: `OnUpdate` 함수는 언제 호출됩니까? 답변: `OnBeginPlay` 함수 호출 이후, 프레임마다 호출됩니다. 질문: `OnUpdate` 함수의 매개 변수 `delta`는 어떤 값을 가지며, 그 단위는 무엇입니까? 답변: `delta`는 이전 프레임에 걸린 시간 값을 가지며, 그 단위는 초입니다. 질문: 프레임별로 엔티티의 위치나 상태를 변경하고 싶을 때 어떤 함수에 스크립트를 작성해야 합니까? 답변: `OnUpdate` 함수에 스크립트를 작성해야 합니다. 질문: 아래 코드는 어떤 기능을 수행합니까? ```lua [original] | `OnBeginPlay` 함수 호출 이후, 프레임마다 호출되는 함수입니다. 따라서 프레임별로 엔티티 위치, 상태, 동작을 변경하고 싶다면 `OnUpdate` 함수에 스크립트를 작성합니다. 매개 변수로 **delta**를 사용하며, 이전 프레임에 걸린 시간 값(단위: 초)을 받습니다. **delta**를 활용하여 프레임 단위 구현을 할 수 있고, 특정 시간마다 액션을 제어할 수 있습니다. ```lua void OnUpdate(number delta) { if self._T.Time == nil then self._T.Time [chunk_id] | Guides:163:2

[task] | wikipedia [title] | MSW 기본 이벤트 함수 [category] | Guides [rephrased] | # MSW 기본 이벤트 함수 메이플스토리 월드 스크립트에서는 엔티티의 생명주기(Lifecycle)와 상태 변경을 관리하기 위해 몇 가지 기본 이벤트 함수를 제공합니다. 이러한 함수들은 특정 시점에 자동으로 호출되며, 각 함수의 매개 변수와 동작 방식을 이해하는 것이 스크립트 작성의 핵심입니다. ## OnUpdate `OnUpdate` 함수는 `OnBeginPlay` 함수가 호출된 이후부터 프레임 단위로 반복적으로 호출되는 함수입니다. 따라서 엔티티의 위치, 상태, 또는 동작을 프레임별로 변경하고자 할 경우 이 함수 내에 로직을 [original] | `OnBeginPlay` 함수 호출 이후, 프레임마다 호출되는 함수입니다. 따라서 프레임별로 엔티티 위치, 상태, 동작을 변경하고 싶다면 `OnUpdate` 함수에 스크립트를 작성합니다. 매개 변수로 **delta**를 사용하며, 이전 프레임에 걸린 시간 값(단위: 초)을 받습니다. **delta**를 활용하여 프레임 단위 구현을 할 수 있고, 특정 시간마다 액션을 제어할 수 있습니다. ```lua void OnUpdate(number delta) { if self._T.Time == nil then self._T.Time [chunk_id] | Guides:163:2

[task] | diverse_qa [title] | MSW 기본 이벤트 함수 [category] | Guides [rephrased] | 질문: 플레이어 엔티티가 map01에서 map02로 이동할 때, 해당 플레이어의 스크립트 컴포넌트에 어떤 함수가 호출됩니까? 답변: 플레이어 엔티티의 스크립트 컴포넌트에 `OnMapEnter` 함수가 존재한다면, map02로 이동할 때 이 함수가 호출됩니다. 질문: 클라이언트 관점에서 내가 map02로 이동했을 때, map02에 있던 다른 플레이어들의 `OnMapEnter` 함수가 호출되는 이유는 무엇입니까? 답변: 클라이언트 상에서 내가 존재하는 맵에 다른 플레이어 엔티티가 새로 생성된 것과 동일한 상황이기 때문에 호출됩니다. [original] | 예를 들어, 내 플레이어 엔티티가 **map01에서 map02로 이동**했다고 가정합니다. 이때 내 플레이어 엔티티의 스크립트 컴포넌트에 `OnMapEnter` 함수가 있었다면, map02로 이동할 때 내 플레이어 엔티티의 `OnMapEnter` 함수가 호출됩니다. 그런데 내 플레이어뿐만 아니라 다른 플레이어의 `OnMapEnter` 함수도 호출되는 것을 볼 수 있습니다. 클라이언트 상에서 보자면, 현재 내가 존재하는 맵에 다른 플레이어 엔티티가 생성된 것과 마찬가지이기 때문입니다. 하지만 서버상에서는 내 플레이어 엔티티가 map [chunk_id] | Guides:163:3

[task] | distill [title] | 엔티티와 컴포넌트 참조 [category] | Guides [rephrased] | ```lua -- _EntityService:GetEntityByPath(worldPath) -- worldPath: string (예: "/maps/map01/object_1") -- 반환: Entity | nil -- 동작: 경로와 일치하는 첫 번째 엔티티를 반환. 없으면 nil. -- 주의: 경로 오타 방지를 위해 에디터에서 'Copy Entity Path' 기능 사용 권장. local EntityE = _EntityService:GetEntityByPath("/maps/map01/EntityO/EntityB/EntityE" [original] | 찾으려는 엔티티 경로(Path)를 매개 변수로 넘겨주면, 해당 경로의 엔티티를 반환하는 함수입니다. 가장 보편적으로 사용되는 함수입니다. * **매개 변수** | Parameter | Type | Description | | --- | --- | --- | | worldPath | string | 얻고자 하는 엔티티 경로를 넣어줍니다. 경로는 /maps/부터 시작해서 하위 엔티티들을 입력합니다. 예를 들어 다음과 같은 계층 구조에서 "object_1"의 경로는 다음과 같습니다. "/maps/map01 [chunk_id] | Guides:164:2

[task] | knowledge_list [title] | 엔티티와 컴포넌트 참조 [category] | Guides [rephrased] | * `Entity:GetChildByName()` 메서드는 매개변수로 전달된 이름과 동일한 하위 엔티티를 직접 반환하여, `Entity.Children`을 통해 전체 목록을 반복문으로 검색할 필요가 없도록 하는 함수입니다. * `Entity:GetChildByName()` 메서드의 첫 번째 매개변수 `name`은 `string` 타입이며, 검색 대상 하위 엔티티의 이름을 지정합니다. * `Entity:GetChildByName()` 메서드의 두 번째 매개변수 `recursive`은 `bool` 타입의 옵션 매개변수이며, `true` [original] | Entity.Children처럼 하위 엔티티를 참조하는 또 다른 방법을 알아봅시다. Entity:GetChildByName()은 하위 엔티티 중 매개 변수로 넘겨진 값과 같은 이름의 엔티티를 반환하는 함수입니다. 따라서 Entity.Children처럼 모든 하위 엔티티를 받아온 후 반복문을 통해 원하는 엔티티를 찾을 필요가 없습니다. 찾고자 하는 엔티티의 이름만 알고 있다면 훨씬 간단하게 하위 엔티티를 가져올 수 있습니다. * **매개 변수** * GetChildByName 함수는 두 개의 매개 변수를 받을 수 있습니다. [chunk_id] | Guides:164:1

[task] | extract_knowledge [title] | Maple GYM 만들기 Ⅱ [category] | Guides [rephrased] | # 구매 처리 및 최대 힘 갱신 ## 1. 개념 설명 이 절에서는 사용자가 실제 화폐(돈)를 소모하여 운동 기술(Skill)과 DNA 등급을 업그레이드하는 로직을 처리합니다. 서버(`[server]`)에서 화폐 검증 및 차감, 등급 상승, 관련 스탯(운동량 보너스, 최대 힘) 갱신 과정을 수행합니다. 이후 클라이언트(`[client]`)와 멀티캐스트(`[multicast]`) 공간을 통해 UI를 최신화하고, 모든 참여자에게 최대 힘 값의 변경을 동기화합니다. ## 2. API 사용법 * **`[server]` 실행 공간* [original] | # 구매 처리 실제 돈이 있는 상태에서 **DnaUpButton**을 클릭했을 때, 운동 기술과 DNA를 업그레이드 할 수 있도록 처리해봅시다. **UIManager**에서 `OnClickButton()`에서**SkillUpButton**와 **DnaUpButton**을 눌렀을 때 동작할 내용을 추가합니다. 1. **PlayerStats** 컴포넌트에서 새로운 `SkillUpgrade()` 메소드를 추가하고, 아래 내용을 입력합니다. 운동 레벨이 증가하면 해당 운동 레벨에 맞는 운동량을 설정하게 됩니다. ```lua [chunk_id] | Guides:143:7

[task] | extract_knowledge [title] | MSW 기본 이벤트 함수 [category] | Guides [rephrased] | # OnBeginPlay 함수 ## 개념 설명 `OnBeginPlay` 함수는 로직 실행 초기 단계인 `OnInitialize` 호출 이후, `OnUpdate` 호출 직전에 1회 실행되는 이벤트 핸들러입니다. 이 함수의 핵심 특징은 **참조 보장**입니다. 엔티티의 `OnBeginPlay`는 해당 엔티티와 모든 컴포넌트가 생성된 이후에 호출됩니다. 동적으로 생성된 엔티티도 마찬가지로, 해당 엔티티의 컴포넌트가 모두 생성된 후에 `OnBeginPlay`가 실행됩니다. 따라서 `OnInitialize`와 달리 다른 엔티티 및 다른 [original] | 본격적으로 로직이 시작되는 시점(`OnInitialize` 함수 호출 이후, `OnUpdate` 호출 직전)에 1회 호출되는 함수입니다. 엔티티의 `OnBeginPlay` 함수는 다른 엔티티와 컴포넌트가 모두 생성된 뒤에 호출됩니다. 동적으로 생성된 엔티티도 해당 엔티티의 컴포넌트가 모두 생성된 후에 `OnBeginPlay` 함수가 호출됩니다. 그러므로 `OnInitialize` 함수와는 달리 `OnBeginPlay` 함수는 다른 엔티티 및 컴포넌트의 참조가 보장됩니다. ```lua void OnBeginPlay() { lo [chunk_id] | Guides:163:1

[task] | wikipedia [title] | 엔티티와 컴포넌트 참조 [category] | Guides [rephrased] | # 엔티티와 컴포넌트 참조 이 문서는 메이플스토리 월드(mLua) 환경에서 엔티티(Entity)와 컴포넌트(Component)의 구조를 이해하고, 스크립트를 통해 이러한 객체에 접근하는 방법을 설명합니다. ## 엔티티와 컴포넌트 구조 메이플스토리 월드의 객체 구조는 엔티티가 다양한 컴포넌트들로 구성되며, 엔티티끼리 상위-하위 계층 구조로 연결되어 있는 특징을 가집니다. 이러한 트리 구조를 활용하면 특정 컴포넌트에서 다른 엔티티나 컴포넌트로의 접근이 가능합니다. 엔티티와 컴포넌트의 기본 개념에 대한 더 자세한 설명은 'Entit [original] | # 학습 과정 소개 엔티티와 컴포넌트 구조를 간략하게 이해하고, 스크립트를 통해 엔티티와 컴포넌트에 접근하는 방법을 알아봅니다. # 엔티티와 컴포넌트 구조 먼저 엔티티와 컴포넌트의 구조를 알아보겠습니다. 기본적으로 엔티티는 각기 다른 컴포넌트들로 구성되어 있고, 각각의 엔티티는 상위, 하위 관계로 연결되어 있습니다. 이 연결 구조를 이용하면 특정 컴포넌트에서 다른 엔티티나 컴포넌트로 접근할 수 있습니다. 아래 이미지는 엔티티 간의 상-하위 구조와 각 엔티티를 구성하는 컴포넌트를 도식화한 것입니다. 이후 이 구조를 바탕으로 설명 [chunk_id] | Guides:164:0

[task] | diverse_qa [title] | MSW 기본 이벤트 함수 [category] | Guides [rephrased] | 질문: `OnSyncProperty` 함수는 어떤 시점에 클라이언트에서 호출되나요? 답변: 서버에서 변경된 값이 클라이언트로 동기화될 때 클라이언트에서 호출됩니다. 질문: `OnSyncProperty` 함수의 매개 변수로 어떤 값들이 전달되나요? 답변: 동기화된 프로퍼티의 이름(name)과 변경된 프로퍼티의 값(value)이 매개 변수로 넘어옵니다. 질문: 프로퍼티의 동기화 설정이 'None'으로 되어 있을 때 `OnSyncProperty` 함수는 호출되나요? 답변: 아니요, 프로퍼티 동기화 설정을 None으로 하면 동기화가 이 [original] | 서버에서 변경된 값이 클라이언트로 동기화될 때 클라이언트에서 호출되는 함수입니다. `OnSyncProperty` 함수를 호출하면 동기화된 프로퍼티의 이름과 값이 매개 변수로 넘어옵니다. 프로퍼티 동기화 설정을 **None**으로 하면 동기화가 이루어지지 않으므로 `OnSyncProperty` 함수는 호출되지 않습니다. ```lua Property: [Sync] number HP = 100 [Sync] number MP = 100 Method: [Client Only] void OnSyncProperty(string name, [chunk_id] | Guides:163:4

[task] | extract_knowledge [title] | MSW 기본 이벤트 함수 [category] | Guides [rephrased] | # 프로퍼티 동기화 이벤트: OnSyncProperty ## 개념 설명 `OnSyncProperty`는 서버에서 변경된 `[Sync]` 프로퍼티의 값이 클라이언트로 동기화 완료된 시점에 클라이언트 측에서 호출되는 이벤트 핸들러 함수입니다. 이 함수는 동기화된 프로퍼티의 이름과 변경된 값을 매개변수로 전달받습니다. **주의:** 프로퍼티의 동기화 설정이 `[None]`으로 지정된 경우, 해당 프로퍼티는 동기화되지 않으며 `OnSyncProperty` 함수는 호출되지 않습니다. ## API 사용법 * **함수 시그니처**: ` [original] | 서버에서 변경된 값이 클라이언트로 동기화될 때 클라이언트에서 호출되는 함수입니다. `OnSyncProperty` 함수를 호출하면 동기화된 프로퍼티의 이름과 값이 매개 변수로 넘어옵니다. 프로퍼티 동기화 설정을 **None**으로 하면 동기화가 이루어지지 않으므로 `OnSyncProperty` 함수는 호출되지 않습니다. ```lua Property: [Sync] number HP = 100 [Sync] number MP = 100 Method: [Client Only] void OnSyncProperty(string name, [chunk_id] | Guides:163:4

[task] | extract_knowledge [title] | MSW 기본 이벤트 함수 [category] | Guides [rephrased] | # MSW 기본 이벤트 함수: 맵 진입/퇴장 및 동기화 ## 1. 개념 설명 메이플스토리 월드(mLua)에서는 엔티티의 상태 변화에 따라 자동으로 호출되는 **기본 이벤트 함수**들이 존재합니다. 특히 맵 이동과 관련된 `OnMapEnter`와 `OnMapLeave` 함수는 클라이언트와 서버에서 동작 방식이 다르므로, 이를 정확히 이해하는 것이 중요합니다. * **클라이언트 관점:** 내가 있는 맵에 다른 플레이어가 들어오는 것은 해당 플레이어 엔티티가 새로 생성되는 것과 같습니다. 따라서 다른 플레이어의 `OnMapEnt [original] | 예를 들어, 내 플레이어 엔티티가 **map01에서 map02로 이동**했다고 가정합니다. 이때 내 플레이어 엔티티의 스크립트 컴포넌트에 `OnMapEnter` 함수가 있었다면, map02로 이동할 때 내 플레이어 엔티티의 `OnMapEnter` 함수가 호출됩니다. 그런데 내 플레이어뿐만 아니라 다른 플레이어의 `OnMapEnter` 함수도 호출되는 것을 볼 수 있습니다. 클라이언트 상에서 보자면, 현재 내가 존재하는 맵에 다른 플레이어 엔티티가 생성된 것과 마찬가지이기 때문입니다. 하지만 서버상에서는 내 플레이어 엔티티가 map [chunk_id] | Guides:163:3

[task] | knowledge_list [title] | 엔티티와 컴포넌트 참조 [category] | Guides [rephrased] | 제시된 문서의 내용만 바탕으로 `_EntityService` 의 엔티티 경로 기반 조회 API 핵심 사실을 정리하면 다음과 같습니다. 1. `_EntityService:GetEntityByPath(string worldPath)` 함수는 매개변수로 `/maps/` 로 시작하는 엔티티 경로 문자열을 받아, 해당 경로와 일치하는 엔티티를 반환하며, 일치하는 엔티티가 없거나 여러 개일 경우 가장 먼저 찾은 엔티티 하나만 반환하고 존재하지 않으면 `nil` 을 반환합니다. 2. `_EntityService:GetEntitiesByPa [original] | 찾으려는 엔티티 경로(Path)를 매개 변수로 넘겨주면, 해당 경로의 엔티티를 반환하는 함수입니다. 가장 보편적으로 사용되는 함수입니다. * **매개 변수** | Parameter | Type | Description | | --- | --- | --- | | worldPath | string | 얻고자 하는 엔티티 경로를 넣어줍니다. 경로는 /maps/부터 시작해서 하위 엔티티들을 입력합니다. 예를 들어 다음과 같은 계층 구조에서 "object_1"의 경로는 다음과 같습니다. "/maps/map01 [chunk_id] | Guides:164:2

[task] | knowledge_list [title] | 엔티티와 컴포넌트 참조 [category] | Guides [rephrased] | 제시된 문서의 내용만 바탕으로 핵심 사실을 추출하여 목록으로 정리합니다. 1. `_EntityService:GetEntity` 함수는 매개변수로 `string` 타입의 엔티티 ID를 입력받아 해당 ID를 가진 `Entity` 객체를 반환하며, 해당 ID의 엔티티가 존재하지 않을 경우 `nil`을 반환합니다. 2. 엔티티의 계층 구조가 동적으로 변경되거나 이름 변경으로 경로가 변할 가능성이 있을 때, `_EntityService:GetEntity`를 사용해 유니크한 ID로 엔티티를 참조하는 것이 효율적입니다. 3. 엔티티의 고유 I [original] | 매개 변수로 엔티티 ID를 넘겨주면 해당 ID의 엔티티를 반환하는 함수입니다. 엔티티의 계층 구조가 동적으로 변경되거나 엔티티의 이름이 바뀌면서 경로가 변경될 여지가 있으면, 유니크한 ID를 이용해 엔티티를 받아올 수 있는 GetEntity를 사용하는 것이 효율적입니다. * **매개 변수** | Parameter | Type | Description | | --- | --- | --- | | ID | string | 얻고자 하는 엔티티 ID를 넣어줍니다. 엔티티의 콘텍스트 메뉴에서 **Copy Entity I [chunk_id] | Guides:164:3

[task] | distill [title] | 엔티티와 컴포넌트 참조 [category] | Guides [rephrased] | ### GetEntity 엔티티 ID를 인자로 받아 해당 엔티티를 반환합니다. 경로가 변경될 수 있는 경우 ID 참조가 효율적입니다. **매개 변수** * `ID` (`string`): 대상 엔티티의 고유 ID. * UI: 엔티티 컨텍스트 메뉴 > **Copy Entity ID** * 코드: `local id = Entity.ID` **반환 값** * 대상 엔티티 또는 `nil` (존재하지 않는 경우) **예시** ```lua void OnBeginPlay() { local entityE = [original] | 매개 변수로 엔티티 ID를 넘겨주면 해당 ID의 엔티티를 반환하는 함수입니다. 엔티티의 계층 구조가 동적으로 변경되거나 엔티티의 이름이 바뀌면서 경로가 변경될 여지가 있으면, 유니크한 ID를 이용해 엔티티를 받아올 수 있는 GetEntity를 사용하는 것이 효율적입니다. * **매개 변수** | Parameter | Type | Description | | --- | --- | --- | | ID | string | 얻고자 하는 엔티티 ID를 넣어줍니다. 엔티티의 콘텍스트 메뉴에서 **Copy Entity I [chunk_id] | Guides:164:3

[task] | diverse_qa [title] | 엔티티와 컴포넌트 참조 [category] | Guides [rephrased] | 질문: 엔티티와 컴포넌트의 기본 구조는 어떻게 되어 있나요? 답변: 엔티티는 각기 다른 컴포넌트들로 구성되어 있으며, 엔티티 간에는 상위와 하위 관계로 연결되어 있습니다. 질문: 스크립트 컴포넌트에서 자신을 포함하는 엔티티를 참조하는 방법은 무엇인가요? 답변: self.Entity를 통해 현재 컴포넌트가 속한 엔티티를 참조할 수 있습니다. 질문: 다음 코드가 수행하는 동작은 무엇인가요? ```lua void OnBeginPlay() { local myEntity = self.Entity log(myEntity.Na [original] | # 학습 과정 소개 엔티티와 컴포넌트 구조를 간략하게 이해하고, 스크립트를 통해 엔티티와 컴포넌트에 접근하는 방법을 알아봅니다. # 엔티티와 컴포넌트 구조 먼저 엔티티와 컴포넌트의 구조를 알아보겠습니다. 기본적으로 엔티티는 각기 다른 컴포넌트들로 구성되어 있고, 각각의 엔티티는 상위, 하위 관계로 연결되어 있습니다. 이 연결 구조를 이용하면 특정 컴포넌트에서 다른 엔티티나 컴포넌트로 접근할 수 있습니다. 아래 이미지는 엔티티 간의 상-하위 구조와 각 엔티티를 구성하는 컴포넌트를 도식화한 것입니다. 이후 이 구조를 바탕으로 설명 [chunk_id] | Guides:164:0

[task] | extract_knowledge [title] | 엔티티와 컴포넌트 참조 [category] | Guides [rephrased] | # 엔티티와 컴포넌트 구조 및 참조 ## 1. 개념 설명 메이플스토리 월드의 객체 구조는 **엔티티(Entity)** 와 **컴포넌트(Component)** 로 구성됩니다. * **엔티티**: 게임 내의 개별 객체(캐릭터, 아이템, 구조물 등)를 나타내는 단위입니다. * **컴포넌트**: 엔티티에 기능을 부여하는 모듈입니다. 하나의 엔티티는 여러 개의 컴포넌트를 가질 수 있습니다. * **계층 구조**: 엔티티는 상하위(Hierarchy) 관계로 연결됩니다. 부모 엔티티와 자식 엔티티의 연결 구조를 통해 다른 엔티티 [original] | # 학습 과정 소개 엔티티와 컴포넌트 구조를 간략하게 이해하고, 스크립트를 통해 엔티티와 컴포넌트에 접근하는 방법을 알아봅니다. # 엔티티와 컴포넌트 구조 먼저 엔티티와 컴포넌트의 구조를 알아보겠습니다. 기본적으로 엔티티는 각기 다른 컴포넌트들로 구성되어 있고, 각각의 엔티티는 상위, 하위 관계로 연결되어 있습니다. 이 연결 구조를 이용하면 특정 컴포넌트에서 다른 엔티티나 컴포넌트로 접근할 수 있습니다. 아래 이미지는 엔티티 간의 상-하위 구조와 각 엔티티를 구성하는 컴포넌트를 도식화한 것입니다. 이후 이 구조를 바탕으로 설명 [chunk_id] | Guides:164:0

[task] | diverse_qa [title] | 엔티티와 컴포넌트 참조 [category] | Guides [rephrased] | 질문: `Entity:GetChildByName()` 함수의 주요 목적은 무엇인가요? 답변: 하위 엔티티 중 매개 변수로 넘겨진 값과 같은 이름의 엔티티를 반환하여, `Entity.Children`처럼 모든 하위 엔티티를 반복문으로 탐색할 필요 없이 원하는 엔티티를 간단하게 가져오기 위한 것입니다. 질문: `GetChildByName` 함수는 몇 개의 매개 변수를 받을 수 있으며, 각각의 이름과 타입은 무엇인가요? 답변: 두 개의 매개 변수를 받을 수 있습니다. 첫 번째는 찾고자 하는 하위 엔티티의 이름을 넘겨주는 `string` [original] | Entity.Children처럼 하위 엔티티를 참조하는 또 다른 방법을 알아봅시다. Entity:GetChildByName()은 하위 엔티티 중 매개 변수로 넘겨진 값과 같은 이름의 엔티티를 반환하는 함수입니다. 따라서 Entity.Children처럼 모든 하위 엔티티를 받아온 후 반복문을 통해 원하는 엔티티를 찾을 필요가 없습니다. 찾고자 하는 엔티티의 이름만 알고 있다면 훨씬 간단하게 하위 엔티티를 가져올 수 있습니다. * **매개 변수** * GetChildByName 함수는 두 개의 매개 변수를 받을 수 있습니다. [chunk_id] | Guides:164:1

[task] | wikipedia [title] | 엔티티와 컴포넌트 참조 [category] | Guides [rephrased] | # 엔티티와 컴포넌트 참조 엔티티를 참조하는 방법에는 `Entity.Children` 속성을 통해 하위 엔티티 목록을 가져오는 방식과 `Entity:GetChildByName()` 메서드를 사용하는 방식이 있습니다. `Entity:GetChildByName()`은 매개 변수로 전달된 이름과 일치하는 하위 엔티티를 직접 반환하므로, `Entity.Children`처럼 전체 목록을 가져온 뒤 반복문을 이용해 특정 엔티티를 검색할 필요가 없습니다. 찾고자 하는 엔티티의 이름만 명확하다면 이 메서드를 사용하는 것이 훨씬 간결합니다. # [original] | Entity.Children처럼 하위 엔티티를 참조하는 또 다른 방법을 알아봅시다. Entity:GetChildByName()은 하위 엔티티 중 매개 변수로 넘겨진 값과 같은 이름의 엔티티를 반환하는 함수입니다. 따라서 Entity.Children처럼 모든 하위 엔티티를 받아온 후 반복문을 통해 원하는 엔티티를 찾을 필요가 없습니다. 찾고자 하는 엔티티의 이름만 알고 있다면 훨씬 간단하게 하위 엔티티를 가져올 수 있습니다. * **매개 변수** * GetChildByName 함수는 두 개의 매개 변수를 받을 수 있습니다. [chunk_id] | Guides:164:1

[task] | extract_knowledge [title] | MSW 기본 이벤트 함수 [category] | Guides [rephrased] | # MSW 기본 이벤트 함수 ## 개념 설명 메이플스토리 월드(MapleStory Worlds)의 mLua 스크립트 컴포넌트는 엔티티의 생명주기 및 상태 변화에 따라 특정 시점에 자동 호출되는 기본 이벤트 함수를 제공합니다. 주요 함수들은 다음과 같습니다. * **`OnUpdate`**: `OnBeginPlay` 함수 호출 이후, 프레임마다 반복적으로 호출됩니다. 프레임 단위로 엔티티의 위치, 상태, 동작을 변경할 때 사용됩니다. * **`OnEndPlay`**: 엔티티가 제거되는 시점에 1회 호출됩니다. 이 함수가 완 [original] | `OnBeginPlay` 함수 호출 이후, 프레임마다 호출되는 함수입니다. 따라서 프레임별로 엔티티 위치, 상태, 동작을 변경하고 싶다면 `OnUpdate` 함수에 스크립트를 작성합니다. 매개 변수로 **delta**를 사용하며, 이전 프레임에 걸린 시간 값(단위: 초)을 받습니다. **delta**를 활용하여 프레임 단위 구현을 할 수 있고, 특정 시간마다 액션을 제어할 수 있습니다. ```lua void OnUpdate(number delta) { if self._T.Time == nil then self._T.Time [chunk_id] | Guides:163:2

[task] | knowledge_list [title] | 엔티티와 컴포넌트 참조 [category] | Guides [rephrased] | * `_UserService.UserEntities`는 게임에 접속해 있는 모든 플레이어 엔티티를 Key가 `string` 타입의 `UserId`, Value가 `Entity` 타입의 `PlayerEntity`인 딕셔너리 형태로 반환하는 읽기 전용 프로퍼티입니다. * `_UserService.UserEntities`의 Key인 `UserId`는 유저가 메이플스토리 월드에 가입 시 생성된 Id이며, 현재 시스템에서는 플레이어 엔티티의 이름(`Name`)과 동일한 값으로 사용되고 있습니다. * `_UserService.Loc [original] | 게임에 접속해 있는 모든 플레이어 엔티티를 딕셔너리 형태로 받아오는 읽기 전용 프로퍼티입니다. * Key: string UserId * Value: Entity PlayerEntity key 값인 UserId는 유저가 메이플스토리 월드에 가입 시 생성한 Id로 UserId와 플레이어 엔티티의 이름을 동일하게 사용하고 있습니다. ```lua void PrintUserEntitiesName() { log(_UserService:GetUserCount()) local playerEntitiesDic = _UserServi [chunk_id] | Guides:164:4

[task] | distill [title] | 엔티티와 컴포넌트 참조 [category] | Guides [rephrased] | # _UserService 및 컴포넌트 접근 ### _UserService.UserEntities 접속 중인 모든 플레이어 엔티티를 딕셔너리로 반환하는 읽기 전용 프로퍼티입니다. * **Key**: `string` (UserId, 가입 시 생성된 ID. 현재 플레이어 엔티티 이름과 동일) * **Value**: `Entity` (PlayerEntity) ```lua void PrintUserEntitiesName() { local playerEntitiesDic = _UserService.UserEntities [original] | 게임에 접속해 있는 모든 플레이어 엔티티를 딕셔너리 형태로 받아오는 읽기 전용 프로퍼티입니다. * Key: string UserId * Value: Entity PlayerEntity key 값인 UserId는 유저가 메이플스토리 월드에 가입 시 생성한 Id로 UserId와 플레이어 엔티티의 이름을 동일하게 사용하고 있습니다. ```lua void PrintUserEntitiesName() { log(_UserService:GetUserCount()) local playerEntitiesDic = _UserServi [chunk_id] | Guides:164:4

[task] | diverse_qa [title] | 엔티티와 컴포넌트 참조 [category] | Guides [rephrased] | 질문: `_EntityService:GetEntityByPath()` 함수의 주요 목적은 무엇인가요? 답변: 찾으려는 엔티티 경로(Path)를 매개 변수로 넘겨주면, 해당 경로의 엔티티를 반환하는 함수입니다. 질문: `GetEntityByPath()` 함수에서 `worldPath` 매개 변수의 타입은 무엇이며, 경로 형식은 어떻게 시작해야 하나요? 답변: `worldPath` 매개 변수의 타입은 `string`이며, 경로는 `/maps/`부터 시작해서 하위 엔티티들을 입력해야 합니다. 질문: 다음 계층 구조에서 "object_1 [original] | 찾으려는 엔티티 경로(Path)를 매개 변수로 넘겨주면, 해당 경로의 엔티티를 반환하는 함수입니다. 가장 보편적으로 사용되는 함수입니다. * **매개 변수** | Parameter | Type | Description | | --- | --- | --- | | worldPath | string | 얻고자 하는 엔티티 경로를 넣어줍니다. 경로는 /maps/부터 시작해서 하위 엔티티들을 입력합니다. 예를 들어 다음과 같은 계층 구조에서 "object_1"의 경로는 다음과 같습니다. "/maps/map01 [chunk_id] | Guides:164:2

[task] | knowledge_list [title] | 엔티티와 컴포넌트 참조 [category] | Guides [rephrased] | 1. 컴포넌트는 엔티티를 작동시키는 구성품이며, 반드시 엔티티를 통해 `Entity.컴포넌트 명` 형태의 접근 방식으로 참조해야 합니다. 2. 네이티브 컴포넌트는 스크립트 에디터에서 컴포넌트 명이 자동 완성되며, `RigidbodyComponent`와 같은 예시를 통해 `myPlayerEntity.RigidbodyComponent` 형태로 접근할 수 있습니다. 3. 스크립트 컴포넌트는 네이티브 컴포넌트와 동일한 접근 방식을 사용하며, 생성 시 작성한 컴포넌트 이름(예: `CharacterStatus`)을 사용하여 `myPlayerE [original] | 컴포넌트는 엔티티를 작동시키는 구성품입니다. 그러므로 반드시 엔티티를 통해 컴포넌트로 접근해야 합니다. 일반적으로 **Entity.컴포넌트 명** 형태로 컴포넌트에 접근할 수 있습니다. 네이티브 컴포넌트는 스크립트 에디터에서 컴포넌트 명이 자동 완성됩니다. 다음은 내 플레이어 엔티티의 **RigidbodyComponent**에 접근하는 예시 코드입니다. ```lua [client only] void OnBeginPlay() { local myPlayerEntity = _UserService.LocalPlayer [chunk_id] | Guides:164:5

[task] | knowledge_list [title] | 엔티티와 컴포넌트 참조 [category] | Guides [rephrased] | 1. `Entity:GetFirstChildComponentByTypeName(string typename, bool recursive)` 메서드는 현재 엔티티의 하위 엔티티들을 순회하여 `typename`과 일치하는 컴포넌트가 있는 첫 번째 엔티티의 해당 컴포넌트를 반환합니다. 2. `typename` 매개변수는 `string` 타입이며, 찾고자 하는 컴포넌트의 이름을 입력합니다. 3. `recursive` 매개변수는 `bool` 타입이며, 하위에 하위 엔티티까지 검색 범위를 확장할지 여부를 설정합니다. 4. `recursive` [original] | > **Component Entity:GetFirstChildComponentByTypeName(string typename, bool recursive)** > 하위 엔티티들을 순회하면서 하위 엔티티에 typename과 일치하는 컴포넌트가 있으면, 해당 컴포넌트를 반환합니다. > * **매개 변수** > > | Parameter | Type | Description | > | --- | --- | --- | > | typename | string | 찾고자 하는 컴포넌트의 이름을 입력합니다. | > [chunk_id] | Guides:164:6

[task] | distill [title] | 엔티티와 컴포넌트 참조 [category] | Guides [rephrased] | # `Entity:GetFirstChildComponentByTypeName` 하위 엔티티를 순회하여 특정 이름의 컴포넌트를 가진 **첫 번째** 엔티티의 해당 컴포넌트를 반환합니다. ### 시그니처 ```lua Component Entity:GetFirstChildComponentByTypeName(string typename, bool recursive) ``` ### 매개 변수 * **`typename`** (`string`): 찾을 컴포넌트 이름. * **`recursive`** (`bool`): * [original] | > **Component Entity:GetFirstChildComponentByTypeName(string typename, bool recursive)** > 하위 엔티티들을 순회하면서 하위 엔티티에 typename과 일치하는 컴포넌트가 있으면, 해당 컴포넌트를 반환합니다. > * **매개 변수** > > | Parameter | Type | Description | > | --- | --- | --- | > | typename | string | 찾고자 하는 컴포넌트의 이름을 입력합니다. | > [chunk_id] | Guides:164:6

[task] | extract_knowledge [title] | 엔티티와 컴포넌트 참조 [category] | Guides [rephrased] | # 엔티티 참조: GetChildByName()과 _EntityService mLua에서는 스크립트 컴포넌트 내에서 다른 엔티티를 참조하기 위해 두 가지 주요 방법을 제공합니다. 하나는 현재 엔티티의 계층 구조(부모-자식 관계)를 따라가는 방식이고, 다른 하나는 경로(Path)를 통해 전역적으로 엔티티를 검색하는 방식입니다. ## 1. 하위 엔티티 참조: `Entity:GetChildByName()` `Entity.Children` 속성은 모든 하위 엔티티 목록을 반환하므로 특정 엔티티를 찾기 위해 반복문이 필요합니다. 반면, [original] | Entity.Children처럼 하위 엔티티를 참조하는 또 다른 방법을 알아봅시다. Entity:GetChildByName()은 하위 엔티티 중 매개 변수로 넘겨진 값과 같은 이름의 엔티티를 반환하는 함수입니다. 따라서 Entity.Children처럼 모든 하위 엔티티를 받아온 후 반복문을 통해 원하는 엔티티를 찾을 필요가 없습니다. 찾고자 하는 엔티티의 이름만 알고 있다면 훨씬 간단하게 하위 엔티티를 가져올 수 있습니다. * **매개 변수** * GetChildByName 함수는 두 개의 매개 변수를 받을 수 있습니다. [chunk_id] | Guides:164:1