스크립트 개요와 엔진 API

스크립트는 게임의 규칙과 움직임을 정하는 JavaScript 파일입니다. 공을 키로 굴리고, 별을 먹으면 점수를 올리고, 시간이 다 되면 게임을 끝내는 일이 모두 스크립트에서 일어납니다. 이 페이지는 OasisW에서 스크립트가 어디에 있고 어떻게 실행되는지, 그리고 엔진 API를 어디서 찾는지 설명합니다.

OasisW 스크립트의 특징

• 에셋입니다. 스크립트 파일은 ASSETS에 있는 에셋이고, 프로젝트의 모든 씬이 함께 씁니다. 한 씬에서 스크립트를 고치면 그 스크립트를 쓰는 다른 씬도 바뀝니다(씬마다 따로인 것, 프로젝트가 함께 쓰는 것).
• 엔티티에 붙여야 실행됩니다. 파일만 있으면 아무 일도 하지 않습니다. 엔티티의 SCRIPT 컴포넌트에 붙이면, 게임이 시작될 때 그 엔티티마다 하나씩 실행됩니다(새 스크립트 만들고 붙이기).
• 속성으로 값을 밖에 꺼냅니다. 속도·점수 문구 같은 값을 스크립트 속성으로 선언하면, 코드를 열지 않고 SCRIPT 칸에서 바꿀 수 있습니다(스크립트 속성 정의하기).
• AI가 쓴 코드도 같은 형식입니다. AI GAME BUILDER가 만든 스크립트와 + → Script로 만든 스크립트는 같은 뼈대를 씁니다. 그래서 AI가 만든 코드를 직접 읽고 고칠 수 있습니다(AI가 만든 코드 읽고 고치기).

스크립트 형식

OasisW 스크립트는 ow.createScript('이름')으로 스크립트 종류를 만들고, 그 prototype에 함수를 붙이는 형식입니다. + → Script로 만든 새 파일은 다음과 같습니다(2026-10-29 확인).

var PlayHit = ow.createScript('playHit');

// initialize 코드는 엔티티마다 1회 실행됩니다
PlayHit.prototype.initialize = function () {};

// update 코드는 매 프레임 호출됩니다 (dt = 지난 프레임 이후 초)
PlayHit.prototype.update = function (dt) {};

// 아래 swap 주석을 풀면 런치 중 코드를 고칠 때 이 스크립트가 핫 리로드됩니다
// 본문에서 옛 인스턴스(old)의 상태를 새 인스턴스로 옮기세요
// PlayHit.prototype.swap = function (old) {};

파일 끝의 swap은 Launch한 게임을 켜 둔 채 코드를 고쳤을 때, 게임을 다시 시작하지 않고 새 코드로 바꿔 끼우는 데 씁니다. 2026-10-30 실측에서 swap을 정의한 스크립트를 쓰는 게임을 Launch 탭에 켜 둔 채, 에디터에서 그 파일에 postUpdate를 더해 저장했습니다. 게임 탭을 새로 고치지 않았는데 swap이 1번 불리고 새 postUpdate가 실행됐습니다(1회). 각 함수가 언제 불리는지는 스크립트 구조와 라이프사이클에 있습니다.

엔진의 클래스와 상수는 ow로 시작합니다. 예: ow.Vec3, ow.StandardMaterial, ow.KEY_LEFT. 스크립트 안에서 this.entity는 스크립트가 붙은 엔티티, this.app은 게임 전체입니다.

엔진 API

OasisW의 엔진 API는 PlayCanvas 엔진과 호환됩니다. 클래스·함수·이벤트의 전체 목록은 PlayCanvas Engine API 문서에서 찾습니다. 문서의 pc.는 OasisW 스크립트에서 ow.로 바꿔 씁니다.

이 매뉴얼은 API 전체를 따로 설명하지 않습니다. 대신 각 페이지에서 OasisW로 실행해 본 코드만 싣습니다.

다음으로

• 스크립트 구조와 라이프사이클
• 새 스크립트 만들고 붙이기
• 코드 편집기