> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/text.md). # 텍스트 씬에 텍스트를 추가하는 방법 다음을 사용하여 장면에 텍스트를 추가합니다 `TextShape` 컴포넌트. 이 텍스트는 위치에 배치됩니다 Decentraland의 텍스트는 모든 *utf8* 문자를 지원하며, 여기에는 동양 문자와 특수 문자가 포함됩니다. {% hint style="warning" %} **📔 참고**: 이 컴포넌트는 플레이어의 2D HUD UI가 아니라 장면의 3D 공간에 존재하는 인월드 레이블과 UI에 유용합니다. {% endhint %} 기존 엔티티에 레이블로 텍스트를 추가하려면, 다음을 가진 두 번째 엔티티를 만드는 것이 좋습니다 `TextShape` 컴포넌트를 추가하고 이를 다른 엔티티의 자식으로 설정합니다. ## Creator Hub의 Scene Editor를 사용하세요 인월드에 텍스트를 배치하는 가장 쉬운 방법은 다음을 추가하는 것입니다 **텍스트** [스마트 아이템](/creator/content-creator-ko/scene-editor/interactivity/smart-items.md) Scene Editor에서 시각적으로 추가하는 것입니다. 그런 다음 Scene Editor의 UI에서 사용 가능한 모든 필드를 설정할 수 있습니다. ![](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-e555db49c09743be8685fc9f249cfd2ab00480f0%2Ftext-smart-item.png?alt=media) ## 텍스트 컴포넌트 생성 다음 예제는 다음을 만드는 방법을 보여줍니다 `TextShape` 컴포넌트를 코드로 엔티티에 추가하는 방법입니다. ```ts const sign = engine.addEntity() Transform.create(sign, { position: Vector3.create(8, 1, 8), }) TextShape.create(sign, { text: '안녕하세요, 세계', }) ``` {% hint style="warning" %} **📔 참고**: 텍스트 컴포넌트가 있는 엔티티가 다른 엔티티의 자식인 경우, 부모의 스케일 영향을 받습니다. 부모가 축 방향으로 불균등하게 스케일되면 텍스트도 늘어나거나 압축됩니다. {% endhint %} {% hint style="warning" %} **📔 참고**: `TextShape` 컴포넌트는 클릭할 수 없습니다. `PointerEvents` 컴포넌트는 다음이 있는 엔티티에 사용될 때 활성화되지 않습니다 `TextShape` 컴포넌트를 부여해야 합니다. {% endhint %} {% hint style="warning" %} **📔 참고**: `TextShape` 는 다음을 통해 가져와야 합니다 > `import { TextShape } from "@dcl/sdk/ecs"` 참고 [가져오기](/creator/content-creator-ko/sdk7/getting-started/coding-scenes.md#imports) 를 사용하면 이를 쉽게 처리할 수 있습니다. {% endhint %} ## 텍스트 값 변경 새 텍스트 컴포넌트를 만들 때 표시할 문자열을 할당합니다. 이 문자열은 다음에 저장됩니다 `text` 필드에 붙여 넣어 자체 스트리밍 인프라를 지정하세요. 컴포넌트가 표시하는 문자열을 변경하려면 다음을 변경하여 언제든지 할 수 있습니다 `text` 필드를 가진 [가변 버전](/creator/content-creator-ko/sdk7/programming-patterns/mutable-data.md) 의 컴포넌트. ```ts const mutableText = TextShape.getMutable(myEntity) mutableText.text = '새 문자열' ``` ## 기본 텍스트 속성 그 `TextShape` 컴포넌트에는 텍스트 스타일을 지정할 수 있는 여러 속성이 있습니다. 아래는 가장 일반적인 것들입니다: * `font`: enum의 값 `Font`. * `fontSize`: *number*. font 10인 엔티티의 높이는 1미터입니다. * `textColor`: *Color4* 객체. *Color4* 객체는 다음을 저장합니다 *RBG* 색상을 0에서 1까지의 세 숫자와 함께 *alpha* 투명도를 위한 값을 저장합니다. 다음을 참조하세요 [색상 유형](/creator/content-creator-ko/sdk7/3d/color-types.md) 자세한 내용은 다음을 참조하세요. ```ts TextShape.create(sign, { text: '안녕하세요, 세계', textColor: { r: 1, g: 0, b: 0, a: 1 }, fontSize: 5, font: Font.F_SANS_SERIF, }) ``` ## 글꼴 텍스트 셰이프는 enum의 글꼴을 사용할 수 있습니다 `Font`. 현재 이 enum에는 다음 글꼴이 포함되어 있습니다: * `Font.F_SANS_SERIF` * `Font.F_SERIF` * `Font.F_MONOSPACE` 기본적으로는 이를 사용합니다 `Font.F_SANS_SERIF`. ```ts TextShape.create(sign, { text: '안녕하세요, 세계', textColor: { r: 1, g: 0, b: 0, a: 1 }, fontSize: 5, font: Font.F_SANS_SERIF, }) ``` {% hint style="warning" %} **📔 참고**: 현재 모든 글꼴은 Sans Serif로 렌더링됩니다. 이는 알려진 문제이며 향후 수정될 예정입니다. {% endhint %} {% hint style="info" %} **💡 팁**: VS Studio나 다른 IDE를 사용하는 경우, 다음을 입력하세요 `Font.` 그러면 사용 가능한 모든 글꼴이 제안 목록으로 표시됩니다. {% endhint %} ## 텍스트 정렬 및 패딩 속성 그 `TextShape` 컴포넌트는 크기, 패딩 등을 가진 텍스트 박스를 생성합니다. * `textAlign`: 다음에서 값을 선택하세요 `TextAlignMode` enum. 가능한 값에는 세로(*상단*, *중간*, *하단*) 및 가로(*left*, *중심*, *right*) 정렬의 모든 조합이 포함됩니다. * `width`: *number*. 텍스트 박스의 너비입니다. * `height`: *number*. 텍스트 박스의 높이입니다. * `paddingTop`: *number*. 텍스트와 텍스트 박스 윤곽선 사이의 공간입니다. * `paddingRight`: *number*. 텍스트와 텍스트 박스 윤곽선 사이의 공간입니다. * `paddingBottom`: *number*. 텍스트와 텍스트 박스 윤곽선 사이의 공간입니다. * `paddingLeft`: *number*. 텍스트와 텍스트 박스 윤곽선 사이의 공간입니다. {% hint style="info" %} **💡 팁**: 텍스트가 공간에 떠 있는 형태라면, 다음을 추가하는 것이 좋습니다 [`빌보드` 컴포넌트](/creator/content-creator-ko/sdk7/3d/entity-positioning.md#face-the-user) 텍스트가 항상 플레이어를 향하도록 회전하여 읽을 수 있게 됩니다. {% endhint %} ## 텍스트 그림자 및 윤곽선 속성 텍스트에는 기본적으로 그림자가 없지만, 다음 값을 설정해 그림자 같은 효과를 줄 수 있습니다. * `shadowBlur`: *number* * `shadowOffsetX`: *number* * `shadowOffsetY`: *number* * `shadowColor`: *Color3* 객체. *Color3* 객체는 다음을 저장합니다 *RBG* 색상은 0에서 1까지의 세 숫자로 표시됩니다. ```ts TextShape.create(sign, { text: '그림자가 있는 텍스트', shadowColor: { r: 1, g: 0, b: 0 }, shadowOffsetY: 1, shadowOffsetX: -1, }) ``` 텍스트의 글자들도 둘레를 따라 다른 색상의 윤곽선을 가질 수 있습니다. * `outlineWidth`: *number*. 텍스트 윤곽선의 너비를 모든 방향에서 0에서 1 사이의 숫자로 나타낸 값입니다. 기본값은 *0*, 이는 윤곽선을 보이지 않게 만듭니다. * `outlineColor`: *Color3* 객체. *Color3* 객체는 다음을 저장합니다 *RBG* 색상은 0에서 1까지의 세 숫자로 표시됩니다. ## 여러 줄 텍스트를 여러 줄에 걸쳐 표시하려면 다음을 사용하세요 `\n` 를 문자열의 일부로 사용하세요. 다음 예제에는 두 개의 별개의 텍스트 줄이 있습니다: ```ts TextShape.create(sign, { text: '이것은 한 줄입니다. \n이것은 다른 줄입니다', }) ``` 여러 줄 텍스트와 관련하여 다음 속성도 설정할 수 있습니다: * `lineCount`: *number*. 텍스트 박스에 최대 몇 줄의 텍스트를 맞출지 나타냅니다. 설정하지 않으면 줄 수에 제한이 없습니다. 다음 `textWrapping` 속성은 다음이어야 합니다 *true* 두 줄 이상 사용하려면 * `lineSpacing`: *number*. 각 줄 사이의 간격입니다. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/text.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.