Object3D

3D 공간의 대부분의 객체가 상속받는 클래스입니다.

속성

.castShadow

object.castShadow : Boolean

object가 그림자를 생성하는지 여부를 설정하는 속성입니다.
기본값은 false입니다.

.children

object.children : Array

object의 자식 객체들을 배열로 반환하는 속성입니다.
개체를 수동으로 그룹화하는 방법에 대한 자세한 내용은 그룹을 참조하세요.

.parent

object.parent : Object3D

object의 객체의 부모 객체를 반환하는 속성입니다.
객체는 최대 하나의 부모만 가질 수 있습니다.

.position

object.position : Vector3

객체의 위치를 나타내는 속성입니다.
이 속성을 통해 객체의 위치를 설정하거나 가져올 수 있습니다.
기본값은 ‘(0, 0, 0)‘입니다.

.quaternion

object.quaternion : Quaternion

객체의 회전을 나타내는 또다른 방식입니다.
이 속성을 통해 객체의 회전 상태를 설정하거나 가져올 수 있습니다.
Quaternion은 Euler 각도와 달리 회전을 보다 정확하게 표현할 수 있습니다.

.receiveShadow

object.receiveShadow : Boolean

객체가 그림자를 받을 수 있는지 여부를 설정하는 속성입니다.
이 속성은 THREE.Mesh 객체나 그와 유사한 객체들에서 사용될 수 있습니다.
기본값은 false입니다.

.rotation

object.rotation : Euler

객체의 회전을 나타내는 속성으로, 라디안 단위입니다.
이 속성을 통해 객체의 회전 각도를 설정하거나 가져올 수 있습니다.

.scale

object.scale : Vector3

객체의 크기를 나타내는 속성입니다.
이 속성을 통해 객체의 크기를 설정하거나 가져올 수 있습니다.
객체의 크기는 씬의 좌표계에 따라 상대적으로 설정됩니다. 따라서 객체가 다른 객체의 자식일 경우 부모 객체의 크기에 영향을 받을 수 있습니다.
기본값은 Vector3( 1, 1, 1 )입니다.

.visible

object.visible : Boolean

객체의 가시성 여부를 설정하거나 가져올 수 있는 속성입니다.
이 속성을 통해 객체가 화면에 표시되는지 여부를 제어할 수 있습니다.
기본값은 true입니다.

메소드

.add()

parentObject.add ( childObject : Object3D, ... ) : this

객체를 다른 객체의 자식으로 추가할 때 사용됩니다.
임의의 개수의 개체를 추가할 수 있습니다.
부모 객체가 이동, 회전, 크기 조정 등의 변화를 하더라도 자식 객체는 독립적으로 그 위치와 회전을 유지합니다.
개체는 최대 하나의 부모를 가질 수 있으므로 이미 부모를 가지고 있었다면 제거된 후 새 부모를 가지게 됩니다.

.attach()

parentObject.attach ( childObject : Object3D ) : this

객체를 다른 객체의 자식으로 추가하면서, 부모 객체의 세계 변환(Transform)을 유지하는 데 사용됩니다.
따라서 부모 객체가 이동, 회전, 크기 조정 등의 변화를 하면, 자식 객체도 그 변화를 반영하여 함께 이동하거나 회전합니다.
add()는 주로 씬에 객체를 추가할 때 사용하며, attach()는 객체 간의 계층 관계를 구성할 때 사용됩니다.

.clone()

originalObject.clone(recursive: Boolean) : Object3D

recursive - true인 경우 이 객체의 자식 객체들도 복제됩니다. 기본값은 true입니다.

객체를 복제하여 새로운 객체를 생성해 반환합니다.
원본 객체의 기하학적 모양, 재질, 위치, 회전, 크기 등을 포함한 속성들을 복사하여 새로운 객체를 생성합니다.
그러나 Physics와 Behavior 속성은 복사되지 않습니다.
또한 .clone()을 사용하여 복제한 오브젝트는 API 확장의 Object3D에 속한 메소드는 사용할 수 없습니다.
해당 메소드들을 사용하고 싶다면 .cloneWithMethods()를 사용하세요.

복제된 객체는 원본 객체와 완전히 독립적이므로, 복제 후의 객체 변화는 원본 객체에 영향을 미치지 않습니다.

const obj = WORLD.getObject("obj");
const clone_obj = obj.clone();
WORLD.add(clone_obj);
clone_obj.position.set(10, 1, 10);

.copy()

originalObject.copy (targetObject : Object3D, recursive : Boolean ) : this

recursive - true인 경우 이 객체의 자식 객체들도 복사됩니다. 기본값은 true입니다.

객체의 속성을 다른 객체로 복사해서 새로운 객체를 만들어내 반환합니다.
이 과정에서 기존 객체(targetObject)는 변경되지 않습니다.

.getObjectById()

object.getObjectById ( id : Integer ) : Object3D

id — 객체 인스턴스의 고유 번호

해당 객체 자체부터 시작하여 자식 객체까지 검색하고, 일치하는 ID가 있는 첫 번째 항목을 반환합니다.
찾지 못하면 null을 반환합니다.

ID는 시간순으로 1, 2, 3, …으로 할당되어 중복되지 않고 유일한 값이며, 새로운 객체마다 1씩 증가합니다.

.getObjectByProperty()

.getObjectByProperty( propertyName : String, value : Any ) : Object3D

propertyName - 검색할 속성 이름입니다.
value - 검색할 속성의 값입니다. 해당 속성이 지정한 값과 일치하는 객체를 검색합니다.

특정 속성 값을 기준으로 씬 그래프에서 객체를 검색하는 메소드입니다. 검색 결과로 일치하는 첫 번째 객체를 반환합니다. 일치하는 객체가 없으면 null을 반환합니다.

.getWorldDirection()

object.getWorldDirection( target : Vector3 ) : Vector3

target 방향을 이 객체가 바라보는 방향과 동일하게 설정하여 반환합니다.
이 메소드는 객체의 월드 공간에서의 방향을 계산하기 위해 씬 그래프를 따라 상위 객체의 변환을 모두 고려합니다.
따라서 객체의 부모가 회전하거나 이동한 경우에도 정확한 월드 공간에서의 방향을 반환합니다.
씬에 포함되지 않은 객체에 대해 이 메소드를 호출하면 예외가 발생할 수 있습니다.

.getWorldPosition()

object.getWorldPosition( target : Vector3 ) : Vector3

target 월드 좌표를 object의 월드 좌표와 동일하게 설정하여 반환합니다.
이 메소드는 객체의 월드 좌표를 계산하기 위해 씬 그래프를 따라 상위 객체의 변환을 모두 고려합니다.
따라서 객체의 부모가 회전하거나 이동한 경우에도 정확한 월드 좌표를 반환합니다.
씬에 포함되지 않은 객체에 대해 이 메소드를 호출하면 예외가 발생할 수 있습니다.

.getWorldQuaternion()

object.getWorldQuaternion ( target : Quaternion ) : Quaternion

target 회전값을 object의 회전값과 동일하게 설정하여 반환합니다.
이 메소드는 객체의 월드 공간에서의 쿼터니언을 계산하기 위해 씬 그래프를 따라 상위 객체의 변환을 모두 고려합니다.
따라서 객체의 부모가 회전하거나 이동한 경우에도 정확한 월드 공간에서의 쿼터니언을 반환합니다.
씬에 포함되지 않은 객체에 대해 이 메소드를 호출하면 예외가 발생할 수 있습니다.

.getWorldScale()

object.getWorldScale( target : Vector3 ) : Vector3

target 스케일을 이 객체의 스케일과 동일하게 설정하여 반환합니다.
이 메소드는 객체의 월드 공간에서의 스케일을 계산하기 위해 씬 그래프를 따라 상위 객체의 변환을 모두 고려합니다.
따라서 객체의 부모가 크기를 조정한 경우에도 정확한 월드 공간에서의 스케일을 반환합니다.
씬에 포함되지 않은 객체에 대해 이 메소드를 호출하면 예외가 발생할 수 있습니다.

.lookAt()

object.lookAt ( target : Vector3 ) : undefined
object.lookAt ( x : Float, y : Float, z : Float ) : undefined

target - THREE.Vector3 타입의 벡터로, 객체가 바라볼 대상의 위치를 지정합니다.
x, y, z - 벡터의 x, y, z 값을 선택적으로 지정할 수 있습니다.

object를 특정 지점(벡터)을 향하도록 회전시키는 메소드입니다.
이 메소드는 객체의 로컬 좌표계 기준으로 회전을 수행합니다. 따라서 부모 객체의 변환에 영향을 받습니다.

.raycast()

.raycast( raycaster : Raycaster, intersects : Array ) : undefined

raycaster - THREE.Raycaster 객체입니다. 이 객체는 광선의 출발점(origin)과 방향(direction)을 설정하여 광선을 정의합니다.
intersects - 교차점(intersection) 정보를 저장할 배열입니다. 광선이 객체와 교차할 경우, 교차점에 대한 정보가 이 배열에 추가됩니다.

광선이 특정 객체에 충돌했는지 여부를 검사하고, 충돌한 객체를 식별하는 데 사용됩니다.
광선과 객체 사이의 충돌을 정확히 계산하기 위해 객체의 메쉬가 필요합니다. 기본적인 THREE.Mesh 또는 이를 상속받는 객체들이 충돌 검사에 사용됩니다.
Mesh, Line 및 Points와 같은 하위 클래스는 레이캐스팅을 사용하기 위해 이 메서드를 구현합니다.

.remove()

parentObject.remove ( childObject : Object3D, ... ) : this

객체를 부모 객체로부터 제거하는 데 사용됩니다.
임의의 수의 객체를 제거할 수 있습니다. 제거된 객체는 다시 다른 부모 객체에 추가하거나 씬에 다시 추가해야만 다시 사용할 수 있습니다.

.removeFromParent()

childObject.removeFromParent () : this

부모 개체에서 이 개체를 제거합니다.

.rotateOnAxis()

object.rotateOnAxis ( axis : Vector3, angle : Float ) : this

axis - THREE.Vector3 타입의 벡터로, 회전의 축을 정의합니다.
angle - 회전 각도로, 라디안 단위로 지정합니다.

객체의 로컬 좌표계에서 지정된 축(axis)을 기준으로 회전시키는 메소드입니다.
객체의 로컬 좌표계를 기준으로 회전하므로, 부모 객체의 변환에 영향을 받지 않습니다.

.rotateOnWorldAxis()

object.rotateOnWorldAxis( axis : Vector3, angle : Float) : this

axis - THREE.Vector3 타입의 벡터로, 회전의 축을 월드 좌표계에서 정의합니다.
angle - 회전 각도로, 라디안 단위로 지정합니다.

객체를 월드 좌표계의 특정 축을 기준으로 회전시킵니다.
이 메소드는 객체의 회전을 객체 자체의 로컬 축이 아니라 월드 좌표계에서 지정된 축을 기준으로 수행합니다.
따라서 객체의 부모 객체의 변환에 영향을 받지 않고 지정된 축을 기준으로 회전합니다.

.traverse()

object.traverse ( callback : Function ) : undefined

callback - 각 객체에 대해 호출될 콜백 함수입니다. 이 함수는 object를 매개변수로 받습니다.

객체의 계층 구조를 순회하며 각 객체에 대해 지정된 콜백 함수를 호출하는 메소드 입니다.