[Matter.js] What's the matter???

🐾들어가며

요즘 한참 공부중인 Matter.js에 대해 정리해보려고 합니다. 아직 제대로 사용하진 못 하지만, GPT랑 놀면서 배우고 있어서 삼각함수만 머리를 싸매면 되기에... 기본적인 내용부터 정리를 시작합니다ㅎㅎ  정리하다보니 욕심이 생겨서 지금 만들고 있던 인형뽑기 집게까지 같이 첨부합니다!

Matter.js 공식 문서 바로가기 > https://brm.io/matter-js/?utm_source=cdnjs&utm_medium=cdnjs_link&utm_campaign=cdnjs_library

✨본격적으로

✅CDN으로 시작해보자

CDN.js라는 사이트에서 Matter.js에 대한 CDN을 잘 제공해주어 해당 CDN을 사용하였습니다.

<script
      src="https://cdnjs.cloudflare.com/ajax/libs/matter-js/0.19.0/matter.js"
      integrity="sha512-rsntMCBgWYEWKl4HtqWmQ3vdHgvSq8CTtJd19YL7lCtKokLPWt7UEoHVabK1uiNfUdaLit8O090no5BZjcz+bw=="
      crossorigin="anonymous"
      referrerpolicy="no-referrer"
    ></script>

✅공식문서의 상태가...

React의 주 라이브러리들의 공식문서만 보다가 Matter.js의 공식문서를 보니 예시코드가 없고 옵션에 대한 설명도 불친절하고... 뭐만 하면 깃허브로 연결해서 직접 찾아야되는 불편함이 있었습니다. 그래서 이번엔 ChatGPT(지피티)를 좀 더 활용해보기로 합니다.

그리고 글을 쓰다가 발견한 커뮤니티! - Matter.js의 깃허브 위키를 보시면 더 많은 커뮤니티 링크가 있습니다!

webflow: https://webflow.com/made-in-webflow/matterjs

커뮤니티에서 비슷한 예시를 찾아 시도해보는 것도 좋을 듯 합니다! 전 사실 코드펜에서 예제 찾은 게 도움이 큽니다.

✅시작하기

Matter.js를 사용하기 위해서는 여러 모듈들을 불러와야 합니다. 정말 많은 모듈을 불러와야 해서 그런지, 파일을 분리해서 사용했을 때 좀 헷갈렸습니다.

// module aliases
export const Engine = Matter.Engine,
  Render = Matter.Render,
  Bodies = Matter.Bodies,
  Body = Matter.Body,
  Mouse = Matter.Mouse,
  Events = Matter.Events,
  Composite = Matter.Composite,
  Runner = Matter.Runner,
  Constraint = Matter.Constraint,
  MouseConstraint = Matter.MouseConstraint;

불러온 모듈을 사용하기 위해서는 가장 먼저 create()에 옵션들을 넣어서(혹은 비워놓고) 변수를 선언해줍니다. new 연산자를 대신하는 듯 합니다.

옵션들에 대한 설명은 공식문서보다는 깃허브 코드에서 보는 것을 추천합니다. 다음은 Body 모듈의 create 옵션을 볼 수 있는 링크입니다.
https://github.com/liabru/matter-js/blob/0b131a499c7479cab246d5d31c2a547dbc8b79eb/src/body/Body.js#L39

파일 경로는 src/* 이며, 파일명이 모듈이름과 같아 금방 찾을 수 있습니다.

이에 대한 기본적인 코드입니다.

//html의 특정 요소가 될 수도 있지만, canvas가 무난.
const canvas = document.querySelector("canvas");

// create an engine
export const engine = Engine.create();

export const canvasHeight = 500, canvasWidth = 500;

// create a renderer
//render의 옵션으로 canvas를 넣거나, html요소라면 elem 옵션에 넣자.
export const render = Render.create({
  canvas: canvas,
  engine: engine,
  options: {
    width: canvasWidth,
    height: canvasHeight,
    wireframes: false, //여러 색을 칠한 상자들이 나온다.
  },
});

export const runner = Runner.create();
Render.run(render);
Runner.run(runner, engine);

// Add mouse control
const mouse = Mouse.create(render.canvas);
const mouseConstraint = MouseConstraint.create(engine, {
  mouse: mouse,
  constraint: {
    stiffness: 0.2,
    render: {
      visible: false,
    },
  },
});

Composite.add(engine.world, mouseConstraint);

//code..

//render의 마우스와 실제 마우스를 연동
//예시에서 코드의 가장 마지막에 넣는다.
render.mouse = mouse;

✅각 모듈에 대해 알아보자

단순히 예시를 만드는 게 아닌 Matter.js에 대해 알아보기로 했으니 각 모듈들이 어떤 역할을 하는지 알아보려고 합니다.
주요 모듈은 진하게 표시한 글씨들입니다.

모듈	설명 - 공식문서 참고 / 번역: 지피티
Engine	세계 시뮬레이션 업데이트를 관리하는 컨트롤러. 엔진 생성 및 조작을 위한 메소드들을 포함. 참고 :Runner
Render	Engine의 인스턴스를 시각화하기 위한 간단한 캔버스 기반 렌더러. 개발 및 디버깅 목적으로 사용되지만 간단한 게임에도 적합. 와이어프레임, 스프라이트 및 뷰포트 지원을 포함한 다양한 그리기 옵션이 포함.
Runner	브라우저 내에서 Engine을 지속적으로 업데이트하는 게임 루프를 제공하는 선택적 유틸리티. 개발 및 디버깅 목적으로 고안되었지만 간단한 게임에도 적합. 자체 게임 루프를 사용 중이라면 Runner 대신에 Engine.update(engine, delta)를 자체 루프에서 호출.
Bodies	직사각형, 원 및 다른 다각형과 같은 일반적으로 사용되는 바디 구성을 갖는 강체 바디 모델을 만드는 팩토리 메서드
Body	강체 바디를 만들고 조작하는 메서드가 포함
Composite	Body, Constraint 및 다른 Composite 객체의 모음. 물리적으로 연결되어 있지 않더라도 여러 부분으로 구성된 복합 객체를 나타낼 수 있는 컨테이너. 컴포지트에는 하나의 본체에서부터 전세계까지 모든 것이 포함. 컴포지트를 수정할 때는 속성을 직접 수정하는 대신 포함된 함수를 사용
Composites	스택 및 체인과 같은 일반적으로 사용되는 구성으로 복합 바디를 만드는 팩토리 메서드
Constraint	제약 조건을 생성하고 조작하는 데 사용되는 메서드가 포함. 두 개체(또는 개체와 고정된 월드 공간 위치) 사이에 고정된 거리를 유지해야 함을 지정하는 데 사용. 강성은 스프링이나 탄성을 만들기 위해 수정 가능.
Mouse	마우스 입력을 생성하고 조작하는 메서드가 포함
MouseConstraint	사용자 상호 작용을 허용하고 마우스 또는 터치를 통해 신체를 이동시키는 기능을 제공
Events	다른 객체에서 이벤트를 발생 및 리스닝
Common	모든 모듈에 공통적으로 사용되는 유틸리티 함수가 포함
Plugin	모듈에 플러그인을 등록하고 설치하는 기능이 포함
Bounds	축인 축에 맞춘 바운딩 박스(AABB)를 생성하고 조작하는 메서드를 포함
Collision	주어진 두 바디 쌍 사이의 충돌을 감지하는 메서드를 포함. 참고: Detecto, Query
Contact	충돌 접촉을 만들고 조작하는 메서드를 포함
Detector	넓은 범위 알고리즘을 사용하여 몸체 목록 간의 충돌을 효율적으로 감지하는 메서드를 포함
Matter	최상위 네임스페이스. 라이브러리 위에 플러그인을 설치하는 함수도 포함
Pair	충돌 쌍을 만들고 조작하는 메서드가 포함
Pairs	충돌 페어 세트를 생성하고 조작하는 메소드가 포함
Query	충돌 쿼리를 수행하는 방법
Resolver	충돌 쌍을 해결하는 방법이 포함
Sleeping	개체의 휴면 상태를 관리하는 메소드가 포함
Svg	SVG 이미지를 벡터 포인트 배열로 변환하는 메소드가 포함. SVGPathSeg 폴리필도 필요
Vector	벡터를 생성하고 조작하는 방법이 포함. 벡터는 엔진의 모든 형상 관련 작업의 기초로 개체 Matter.Vector의 형식은 { x: 0, y: 0 }.
Vertices	Matter.Vector에서 삽입한 추가 인덱싱 속성이 있는 배열. 정점 세트를 생성하고 조작하기 위한 메서드가 포함.

제가 이해한 바론,

Engine이 기본 베이스로 Render와 Runner가 도와주는 역할을 하며, Engine에 Composite를 생성하고, Composite는 Bodies로 생성한 모델들, Constraint 등이 들어있으며, Events로 이벤트를 발생하고, Mouse와 MouseConstraint로 마우스 입력을 조절한다

입니다.

아직 코드만 보고는 정확히 어떤 원리로 동작하는지 잘 모르기 때문에 대략 적는 것이 아쉽습니다...

✅직접 만들어볼까?

간단하게 Constraint를 사용해 연결하여 인형뽑기 집게를 만들어보았습니다. 

간단한 인형뽑기 집게

사실 이걸 만든다고 지피티와 3시간씩 5일 동안 고생을 했지만,,, 결국 엎고 하루만에 다시 만들었던 추억이ㅎㅎ

우선 기본적으로 HTML에 CDN을 사용했습니다. canvas도 잊지 않고 적어줍시다.

<!DOCTYPE html>
<html lang="ko">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <script
      src="https://cdnjs.cloudflare.com/ajax/libs/matter-js/0.19.0/matter.js"
      integrity="sha512-rsntMCBgWYEWKl4HtqWmQ3vdHgvSq8CTtJd19YL7lCtKokLPWt7UEoHVabK1uiNfUdaLit8O090no5BZjcz+bw=="
      crossorigin="anonymous"
      referrerpolicy="no-referrer"
    ></script>
    <title>matterJs</title>
  </head>
  <body>
    <canvas></canvas>
    <script type="module" src="./index.js"></script>
  </body>
 </html>

index.js 파일에서 위에서 언급한 기본 코드를 먼저 세팅해줍니다.

- 사각형(모델) 만들기

기본적으로 사각형을 추가하는 코드는 다음과 같습니다.

const rectangle = Bodies.rectangle(x, y, width, length, {
    ...option,
  });

여담) option에는 여러가지가 들어갈 수 있고 앞에서 말씀드렸듯 github에서 찾아보는 게 좋습니다.

이렇게 사각형을 그냥 만들면 순식간에 화면의 가장 아래로 사라져 버립니다. 중력이 작용하기 때문입니다. 그러므로 중력이 작용해도 canvas 외부로 나가지 않게 사방에 벽을 세워줄 겁니다.

const groundHeight = 20;
const ground = Bodies.rectangle(
  canvasWidth / 2,
  canvasHeight - groundHeight / 2,
  canvasWidth,
  groundHeight,
  {
    isStatic: true,
  }
);

옵션으로 isStatic: true를 주었는데, 중력을 무시하는 것입니다.

또 다른 특이한 점이 눈에 띕니다. x와 y 좌표가 각각 canvasWidth / 2, canvasHeight - groundHeight / 2로 되어있습니다. canvas와는 다르게 사각형을 만들 때 중심좌표를 주기 때문입니다.

왼쪽 상단을 (0,0)으로 봤을 때, 오른쪽으로 갈수록 x 좌표가 아래로 갈수록 y좌표가 증가합니다. 즉, (0,0)의 반대 좌표는 (canvasWidth, canvasHeight)입니다.

canvas는 처음 시작점과 끝점을 잡고 그리기 때문에 초기에는 헷갈리지만 금방 익숙해집니다.

위의 코드를 이용해 사방을 막아줍니다. 벽이 튀어나와서 보는 게 싫다면 캔버스에서 보이진 않게 좌표에 사각형의 길이 / 2를 한 값을 적절히 더해줍니다.

또한 벽을 만들기 전에 화면 밖으로 나갔던 사각형은 계속 존재하기 때문에 성능 이슈가 생길 수 있습니다. 그러니 화면 외부로 나간 모델들은 다 삭제해줍니다.

- 모델 추가 및 삭제하기

Composite.add(engine.world, [ground, leftWall, rightWall]); //추가
Composite.clear(engine.world, rectangle); //연관된 객체 모두 삭제
Composite.remove(engine.world, rectangle);//rectangle 삭제

그렇다면 모델들이 어떻게 밖으로 나갔는지 알 수 있을까요?

바로, 해당 객체의 정보를 콘솔에 찍어봅시다.

객체에는 옵션들에 넣어줬던 정보들도 있습니다. 나중에 어떤 옵션이 궁금한 지 빠르게 확인할 땐 이렇게 콘솔에 찍어도 괜찮을 듯 합니다ㅎㅎ

저기에서 position의 값이 canvas 범위 밖에 있는지 확인하면 됩니다. 이 부분은 조건문으로 처리해서 쉬우나, 화면이 업데이트할 때마다 코드를 실행하진 않습니다. 처음 한 번만 실행할 뿐이죠.

그렇다면! 여기에서 등장하는 것이 바로 이벤트입니다.

- 이벤트 모듈 사용하기

Events.on(mouseConstraint, "mousedown", () => {
 //code ...
});

초기에 mouseConstraint를 선언한 것을 이벤트의 첫번째 인자로, 두번째 인자는 이벤트의 이름을, 세번째는 실행할 콜백함수를 넣어줍니다. 첫번째 인자만 추가된 것을 빼면 기본 이벤트와 생김새가 비슷해서 쉽습니다. 그러나 mouse 이벤트가 좀 적을 뿐입니다. mouseup, mousedown, mousemove 정도..? 그래서 mouseover나 mouseleave 등은 canvas 자체에 addEventListener를 이용해 걸어주기도 합니다.

마우스 이벤트 뿐 아니라, runner도 이벤트의 첫번째 인자로 넣을 수 있습니다. runner의 이벤트들에는 화면 렌더링의 생명주기같은 친구입니다.

• on afterTick
• on afterUpdate
• on beforeTick
• on beforeUpdate
• on tick

이렇게 5가지의 이벤트가 있으며, 이벤트의 인자로 전달할 때는 앞의 on을 빼야 합니다! 이 이벤트들은 requestAnimationFrame으로 작동합니다. << 코드: https://github.com/liabru/matter-js/blob/master/src/core/Runner.js

그러니 runner 이벤트 중 tick(사실 아무거나 상관없을 듯)을 이용해서 외부로 나간 사각형들을 모조리 삭제해줍시다.

Events.on(runner, "tick", () => {
    engine.world.bodies.forEach((body) => {
      const isOutside = body.position.y > canvasHeight;
      if (isOutside) Composite.remove(engine.world, body);
    });
});

와 아직 갈길이 멉니다! 이제 사각형도 만들었고 성능 대비도 했으니 진짜진짜진짜 집게를 만들 차례입니다. 그리고 그전에 하나 더..ㅎㅎ Constraint를 알아봅시다.

(여기까지 인강을 통해 배웠던 내용입니다. 이후부터는 독학 중! - 혹시 눈에 거슬리는 부분 있다면 댓글로 알려주세요~!)

- Constraint 알아보기

Constraint는 모델들을 연결해줍니다. 별도로 선언하지 않으면 모델들의 중점을 기준으로 연결해줍니다. 중력과 공기저항, 마찰력에 영향을 받지만 일단 나사처럼 고정됩니다.

  const constraint = Constraint.create({
    bodyA: rectA,
     //rectA의 로컬좌표로 rectA에게 매달릴 좌표
     //즉, rectB가 매달리게 할 좌표
    pointA: {x : 0, y: 0},
    bodyB: rectB
    //rectB의 로컬좌표로 rectB가 매달린 좌표
    pointB: { x: 0, y: 0 }, 
    length: 0,
  });

이렇게 옵션을 다 채워서 써도 되며, 몇가지는 빠져도 됩니다. << 이 부분은 아직 연구중

여기에서도 좌표(사실 벡터라는 말이 맞다 - 공식문서)가 나오는데, 주석에서도 써놨지만 로컬 좌표를 기준으로 합니다. 이 로컬 좌표는 모델을 만들 때 쓴 중점을 (0,0)으로 봐서 조금이라도 복잡한 도형끼리 연결할 땐 매우 어렵습니다. 특히 회전하는 게 들어가면 sin, cos... 삼각함수를 기본으로 깔아야 합니다. (알고 싶지 않았습니다)

✅인형뽑기 집게 만들기!

이제 진짜진짜진짜진짜 시작할 건데요, 중간에 필요한 개념들을 먼저 설명하고 갑니다. (..아직도..?)

앞서 gif에서도 나오지만, Constraint를 기준으로 회전합니다. 사각형의 각도만 바꾸게 된다면, 중점을 기준으로만 돌 뿐, Constraint를 기준으로 돌지 않습니다.

그래서 필요한 계산은 바로 원 위의 점의 좌표입니다. 중점이 (x, y), 반지름이 r, 회전각이 theta라고 할 때 원 위의 점의 좌표는 ( x + r * cos(theta), y + r * sin(theta) ) 입니다. 중점을 기준으로 어느 위치에 있는 가에 따라서 중점에 더할지, 뺄지를 결정하는 것도 좋지만, 완전히 중점을 기준으로 회전하는 좌표를 구하기 위해선 theta의 값만으로 조절하는 것이 편합니다.

처음에 천장에 매달려 있는 사각형을 만들어줍니다. 더불어 앞으로 자주 쓸 숫자들도 상수로 만들어줍니다.

const DEG_TO_RAD = Math.PI / 180;
const BAR_INIT_LENGTH = 80;
const BAR_INIT_WIDTH = 5;
const BAR_INIT_ANGLE = 60; //첫번째 회전각
const BAR_SECOND_ANGLE = -90; //두번째 회전 각. 음수값으로 고정
const currentMousePosition = mouse.position.x; //마우스의 현재 위치의 x 좌표

const bar = Bodies.rectangle(
    currentMousePosition,
    BAR_INIT_LENGTH,
    BAR_INIT_WIDTH,
    BAR_INIT_LENGTH,
    {
      render: {
        fillStyle: "#fff",
      },
      inertia: Infinity,
    }
);

참고로 집게의 모든 옵션은 bar의 옵션과 동일합니다!

다음으로 천장에 꾸준히 매달려 있게 하기 위해 천장과 연결되는 Constraint를 만들어줍니다.

  const barConstraint = Constraint.create({
    bodyA: bar,
    pointA: { x: 0, y: -BAR_INIT_LENGTH / 2 },
    pointB: { x: currentMousePosition, y: 0 },
    length: 0,
  });

이제 두번째 연결되는 사각형을 만듭니다.

const initialAngleRad = BAR_INIT_ANGLE * DEG_TO_RAD;
const secondAngleRad = BAR_SECOND_ANGLE * DEG_TO_RAD;

const bar_bar1 = Bodies.rectangle(
    currentMousePosition,
    BAR_INIT_LENGTH + BAR_INIT_LENGTH / 2,
    BAR_INIT_WIDTH,
    BAR_INIT_LENGTH / 2,
);
//angle을 기본적으로 중점에 수직으로 바꿔준다.
Body.setAngle(bar_bar1, Math.PI / 2)

const bar1_localPosition = {
	x: parseInt(((BAR_INIT_LENGTH / 2) * Math.cos(initialAngleRad)) / 2),
	y: parseInt(((BAR_INIT_LENGTH / 2) * Math.sin(initialAngleRad)) / 2),
}
//기본 각도를 준 상태에서 추가적으로 돌려준다.
Body.rotate(bar_bar1, initialAngleRad);

//bar의 좌표가 대부분 고정이라 bar1은 허공에다가 고정 가능
const bar1_Constraint = Constraint.create({
    pointA: bar1_localPosition,
    bodyA: bar_bar1,
    pointB: { x: currentMousePosition, y: BAR_INIT_LENGTH },
    length: 0,
});

마지막 사각형을 만듭니다.

const bar_bar1_bar2 = Bodies.rectangle(
    currentMousePosition,
    2 * BAR_INIT_LENGTH + BAR_INIT_LENGTH / 4,
    BAR_INIT_WIDTH,
    BAR_INIT_LENGTH / 4,
    {
      render: {
        fillStyle: "#fff",
      },
    }
  );
  Body.setAngle(bar_bar1_bar2, Math.PI / 2 - secondAngleRad);
  Body.rotate(bar_bar1_bar2, -30);
  
  const bar2_localPosition = {
    x: parseInt(((BAR_INIT_LENGTH / 4) * Math.cos( Math.PI / 2 - secondAngleRad )) / 2),
    y: parseInt(((BAR_INIT_LENGTH / 4) * Math.sin( Math.PI / 2 - secondAngleRad )) / 2),
  }
  
  const bar2_Constraint = Constraint.create({
    bodyA: bar_bar1,
    pointA: { x: -localPosition.x, y: -localPosition.y },
    bodyB: bar_bar1_bar2,
    pointB: bar2_localPosition,
    length: 0,
  });

여기에서 bar1와 bar2는 좌우대칭으로 만들어야 하고, 각도만 대칭으로 해 만들 수 있습니다. 그러니, bar1과 bar2를 선언하는 부분을 함수로 만들고, 함수 내에서 Composite에 add까지 할 수 있도록 외부에 배열을 선언하여 요소로 넣어줍시다.

const composites = [];

function createChain(currentMousePosition, index, rads = []) { /*...code...*/ }

createChain(currentMousePosition, index, [-initialAngleRad, secondAngleRad]);
createChain(currentMousePosition, index, [
Math.PI + initialAngleRad,
-secondAngleRad,
]);

이제 집게가 움직일 수 있도록 이벤트를 달아봅니다. 일부 변수의 위치가 변경된다는 점에 유의해주세요!

let isMove = false;
let isMouseOn = false;
let isDown = true;
let isClick = true;
let index = 0;

Events.on(mouseConstraint, "mousedown", () => {
  isClick = !isMove;
  if (isClick) isMove = true;
});

render.canvas.addEventListener("mouseover", (event) => {
  isMouseOn = true;
});
render.canvas.addEventListener("mouseleave", () => {
  isMouseOn = false;
});

Events.on(runner, "tick", () => {
  const currentMousePosition = mouse.position.x;
  const currentMousePositionY = mouse.position.y;
  let ceilingBarLength = BAR_INIT_LENGTH + index;

  const initialAngleRad =
    BAR_INIT_ANGLE * DEG_TO_RAD - index / currentMousePositionY / 2;
  const secondAngleRad =
    BAR_SECOND_ANGLE * DEG_TO_RAD - index / currentMousePositionY; //initialAngle과 일직선보다 넘지 않게 조절

  composites.forEach((comp) => {
    Composite.remove(engine.world, comp);
  });
  composites.length = 0; // 배열 초기화

  if (ceilingBarLength >= currentMousePositionY * 2) isDown = false;
  if (ceilingBarLength < BAR_INIT_LENGTH) isDown = true;

  createChain(currentMousePosition, index, [-initialAngleRad, secondAngleRad]);
  createChain(currentMousePosition, index, [
    Math.PI + initialAngleRad,
    -secondAngleRad,
  ]);

  if (isMove) {
    if (ceilingBarLength < BAR_INIT_LENGTH && isDown) {
      index = 0;
      isMove = false;
    }
    index = isDown ? index + 2 : index - 2;
  }

  Composite.add(engine.world, composites);
});

 

이렇게 클릭한 곳까지 내려오는 집게 완료!

✔️결론

사실 아직 정리가 잘 안된 코드이기도 하고, 각도 계산에서 좀 많이 헤맸던 터라 코드가 그렇게 깔끔하지 않습니다. 그래서 이 코드들을 조합하면 전체 코드가 되지만, 전체 코드는 좀 더 나중에 인형뽑기가 완료되면 보여드리도록 하겠습니다.

사이드 프로젝트를 준비하면서 최근엔 기획과 디자인만 하느라 개발에 손을 못 대다보니 너무 심심해서 딴짓한 결과입니다. 오랜만에 삼각함수 때문에 아이패드로 하나씩 계산도 해보고 재밌었습니다..........ㅎ