어노테이션 활용하기

# 학습 과정 소개

어노테이션(Annotation)은 코드에 추가하여 사용하는 일종의 메타데이터입니다. 스크립트에 `--` 기호를 사용한 주석(Comment)은 스크립트 작성에 참고 역할만 하는 반면, `---@` 형태로 어노테이션을 작성하면 퀵 인포나 시그니처 헬퍼, 코드 컴플리션 등 스크립트 어시스트의 도움을 받을 수 있습니다. 본 과정을 통해 메이플스토리 월드에서 제공하는 어노테이션의 종류와 활용 방법을 알아봅시다.

> 더 알아보기 퀵 인포, 시그니처 헬퍼, 코드 컴플리션에 대해 자세히 알고 싶다면 [스크립트 에디터 오리엔테이션](/ko/docs/?postId=56) 가이드에서 스크립트 어시스트 항목을 살펴봅시다.

# 변수 타입 지정 : Type Annotation

Type Annotation으로 변수 타입을 명시적으로 지정하면 스크립트 에디터에서 스크립트 어시스트의 도움을 받을 수 있습니다. Type Annotation은 할당문에 사용합니다.

## 사용 방법

Type Annotation은 다음과 같이 사용합니다.

[png](166788442640966b092935ab7482d948c6fc39188d48c)
    
    
    @Component
    script ServerInitializer extends Component
        @ExecSpace("ServerOnly")
        method void OnBeginPlay()
            ---@type string
            local testValue = "test"
        end
    end
    

## 활용 예시

##### 반환 타입을 추론할 수 없는 루아 함수

다음과 같이 반환 타입을 추론할 수 없는 루아 함수의 결괏값을 받을 때도 Type Annotation을 활용합니다.
    
    
    @Component
    script TestFunctionRunner extends Component
        @ExecSpace("ServerOnly")
        method void OnBeginPlay()
            local function TestFunction()
                return "strValue"
            end
            
            local strValue = TestFunction()
        end
    end
    

  


[{"index":"Type Annotation 적용 전","0":"[png](166788677395339c9be52267845a1a38273071868699e)"},{"index":"Type Annotation 적용 후","0":"[png](1667886963732dbed1d6d12984f79bd1922548876854f)"}]

  
##### 여러 값을 할당받는 경우 다음과 같이 여러 값을 할당받을 때도 **Type Annotation**을 활용합니다. ```lua @Component script MultiReturnExample extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() local function TestFunction() return "strValue", 5 end 
    
    
        
        local strValue, intValue = TestFunction()
    end
    

end
    
    
      
    
    | Type Annotation 적용 전 | Type Annotation 적용 후 |
    | :---: | :---: |
    | [png](1667887186926acb2c0f5eac64f118c480078c23b2ac4) | [png](1667892117117387cdcbbe65e4aa08d76b2fc548d48ad) |
      
    
    여러 값을 할당받을 때는 일부만 타입을 지정할 수도 있습니다. 지정한 타입은 앞의 값부터 적용되므로 뒤의 값만 따로 타입을 지정할 수는 없습니다.
    
    | Type Annotation 적용 전 | Type Annotation 일부 적용 후 |
    | :---: | :---: |
    | [png](1667887186926acb2c0f5eac64f118c480078c23b2ac4) | [png](166789228646766e78448a0794b3cb971c4492954f34f) |
    
    
    ## 일반 타입 지정
    일반적인 타입 지정은 아래와 같은 문법으로 작성합니다.
    

@Component script ServerBootstrapper extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@type any end end
    
    
    ##### 사용 예시
    

@Component script ServerInitializer extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@type string local testValue = "test" end end
    
    
      
    
    

@Component script StartupValueInitializer extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@type string, integer local strValue, intValue = "str", 5 end end
    
    
      
    
    단순한 원시 타입 외에도 이벤트, 컴포넌트, 엔티티, Enum 등 다양한 타입을 **Type Annotation**으로 지정할 수 있습니다.
    
    ## Table 타입 지정
    Table은 아래와 같은 문법으로 타입을 지정합니다.
    

@Component script ServerInitializer extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@type table end end
    
    
    ##### 사용 예시
    

@Component script ServerDataInitializer extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@type table local testTable = {} end end
    
    
      
    
    

@Component script ServerEntitySetup extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@type table local testTable = {} end end
    
    
      
    
    

@Component script ServerEntityMap extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@type table local testTable = {} end end
    
    
      
    
    예를 들어 아래와 같이 **Type Annotation**을 지정하면 퀵 인포에서 관련 정보를 확인할 수 있습니다.
    

@Component script DataTableTest extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() local function TestFunction() local testTable = {} testTable[1] = "A" testTable[2] = "B" testTable[3] = "C" end
    
    
        
        ---@type table
        local tableValue = TestFunction()
    end
    

end
    
    
    [png](1667895925609146ce9442a4f4e6da96fc1aa6932f744)
    
    ## Function 타입 지정
    Function은 아래와 같은 문법으로 타입을 지정합니다.
    

@Component script ServerInitializer extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@type function(param_name: any):any end end
    
    
    ##### 사용 예시
    

@Component script ServerStartBehavior extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@type function() local testFunction = function() end end end
    
    
      
    
    

@Component script FunctionInitializer extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@type function(testParamA:string, testParamB:Entity) local testFunction = function(testParamA, testParamB) end end end
    
    
      
    
    

@Component script AttackComponentResolver extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@type function(testParamA:string, testParamB:Entity):AttackComponent local testFunction = function(testParamA, testParamB) return atkComponent end end end
    
    
      
    
    

@Component script AttackFunctionSetup extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@type function(testParamA:string, testParamB:Entity):AttackComponent, string local testFunction = function(testParamA, testParamB) return atkComponent, "strValue" end end end
    
    
      
    
    

@Component script AttackComponentProvider extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@type (function(testParamA:string, testParamB:Entity):AttackComponent, string), Entity local testFunction, testEntity = function(testParamA, testParamB) return atkComponent, "strValue" end, self.Entity end end end
    
    
      
    
    예를 들어 아래와 같이 **Type Annotation**을 지정하면 시그니처 헬퍼의 도움을 받을 수 있습니다.
    

@Component script FunctionProvider extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() local function TestFunction() return function(paramA, paramB) return "strValue", false end end
    
    
        
        ---@type function(paramA:string, paramB:AttackComponent):string, boolean
        local test = TestFunction()
    end
    

end
    
    
    [png](1669633527104fde7bdfed20d4bdb802bdec69d11e4fb)
      
    
    또한 퀵 인포에서도 지정한 타입을 확인할 수 있습니다.
    

@Component script AttackComponentInvoker extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@type function(paramA:string, paramB:AttackComponent):string, boolean local test = TestFunction() local strValue, boolValue = test("param", self.Entity.AttackComponent) end end
    
    
    [png](1667893299258103b46b267b745f882a40a4cbb70c568)
      
    
    여러 값을 반환하는 함수와 함께 다른 값을 지정하고 싶을 때는 괄호를 통해 각각의 타입을 묶어서 구분합니다.
    

@Component script AttackFunctionProvider extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@type (function(paramA:string, paramB:Entity):AttackComponent,string), Entity local testFunction, testEntity = function(testParamA, testParamB) return atkComponent, "strValue" end, self.Entity end end end
    
    
    
    # 매개 변수 타입 지정 : Param Annotation
    
    **Param Annotation**을 사용해 대상이 되는 함수의 매개 변수 타입을 지정하여 스크립트 어시스트의 도움을 받을 수 있습니다. **Param Annotation**은 함수 정의문에 사용합니다.
    
    아래와 같은 문법으로 **Param Annotation**을 사용합니다.
    

@Component script ServerInitializer extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@param param_name any end end
    
    
    ##### 사용 예시
    

@Component script EntityTester extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@param testParamA Entity local function TestFunction(testParamA) end end end
    
    
      
    
    

@Component script TestFunctionInitializer extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@param testParamA Entity \---@param testParamB integer local function TestFunction(testParamA, testParamB)
    
    
        
        end
    end
    

end
    
    
      
    
    기본적으로 루아 함수를 정의하면 매개 변수에 어떤 타입이 들어올지 알 수 없기 때문에 타입 추론을 할 수 없습니다. 이때 **Param Annotation**을 사용해 봅시다.
    
    | Param Annotation 적용 전 | Param Annotation 적용 후 |
    | :---: | :---: |
    | [png](166789361996144188e4993ee4a6a8a4d0bddeb7229ae) | [png](1667893634012f417287ece184076a6dae5259609f80e)   
    [png](1668671082158866bdb58d8bf4710b2df2fab3d00ce47) |
    
    # 반환 타입 지정 : Return Annotation
    
    **Return Annotation**은 대상 함수의 반환 타입을 지정하여 스크립트 어시스트의 도움을 받을 수 있습니다. **Return Annotation**은 함수 정의문에 사용합니다.
    
    아래와 같은 문법으로 **Return Annotation**을 사용합니다.
    

@Component script ServerInitializer extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@return any end end
    
    
    ##### 사용 예시
    

@Component script TestFunction extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@return Entity local function TestFnction(testParamA, testParamB) return self.Entity end end end
    
    
      
    
    

@Component script EntityStringProvider extends Component @ExecSpace("ServerOnly") method void OnBeginPlay() \---@return Entity, string local function TestFunction(testParamA, testParamB) return self.Entity, "strValue" end end end
    
    
      
    
    | Return Annotation 적용 전 | Return Annotation 적용 후 |
    | :---: | :---: |
    | [png](1667893987810443dd08fe02842e19a29e8d2b7d14b54) | [png](1667894003787ca547259d8d0414294064f26fd6569ac) |