gaesup-world 0.0.1

package/README.md

@@ -0,0 +1,51 @@
+# Gaesup World
+
+Web 3D Character Controller and World Platform Library
+
+[![npm (tag)](https://img.shields.io/npm/v/leva?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/leva)
+
+@react-three/fiber
+@react-three/drei
+three @types/three
+@react-three/rapier
+
+Gaesup World는 @react/three-fiber, @react/three-drei, rapier 를 사용하여 웹 3D 환경에서 캐릭터, 비행기, 자동자 등의 컨트롤 도구를 제공하는 라이브러리입니다.
+
+이 컨트롤러는 캐릭터의 움직임, 애니메이션, 상호작용을 쉽게 관리할 수 있도록 설계되었습니다. 가상의 세계에서 캐릭터를 움직이거나 탈것을 쉽게 활용할 수 있고, 미니맵이나 조이스틱 등의 유틸 등도 설계되어 있습니다
+
+## 특징
+
+- React Three Fiber를 기반으로 하는 3D 캐릭터 컨트롤
+- 간단한 API를 통한 캐릭터 움직임 및 애니메이션 제어
+- 확장 가능한 구조로 다양한 커스터마이징 지원
+- 가벼운 라이브러리로 빠른 로딩 및 성능 최적화
+
+## 설치 방법
+
+```bash
+npm install @react-three/fiber @react-three/drei three @types/three @react-three/rapier gaesup-world
+```
+
+또는
+
+```bash
+yarn add @react-three/fiber @react-three/drei three @types/three @react-three/rapier gaesup-world
+```
+
+## 문서
+
+더 자세한 사용 방법 및 API 문서는 [여기](#)를 참조하세요.
+
+## 기여 방법
+
+이 프로젝트에 기여하고 싶으시다면, 다음 단계를 따라주세요:
+
+1. 프로젝트를 Fork합니다.
+2. 새로운 Feature 브랜치를 생성합니다 (`git checkout -b feature/AmazingFeature`).
+3. 변경사항을 Commit합니다 (`git commit -m 'Add some AmazingFeature'`).
+4. 브랜치에 Push합니다 (`git push origin feature/AmazingFeature`).
+5. Pull Request를 생성합니다.
+
+## 라이센스
+
+이 프로젝트는 [MIT 라이센스](LICENSE) 하에 배포됩니다.

package/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/gaesupworld.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>gaesup world | example with react</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/examples/select/main.tsx"></script>
+  </body>
+</html>

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "gaesup-world",
+  "version": "0.0.1",
+  "type": "module",
+  "homepage": "https://jigglypop.github.io/gaesup-world/",
+  "scripts": {
+    "dev": "vite",
+    "prepare": "rm -rf dist && tsc",
+    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "preview": "vite preview",
+    "predeploy": "npm run build",
+    "deploy": "gh-pages -d dist"
+  },
+  "dependencies": {
+    "@dimforge/rapier3d": "^0.11.2",
+    "@emotion/react": "^11.11.1",
+    "@mdx-js/loader": "^3.0.0",
+    "@mdx-js/react": "^3.0.0",
+    "@next/mdx": "^14.0.1",
+    "@react-icons/all-files": "^4.1.0",
+    "@react-three/drei": "9.88.11",
+    "@react-three/fiber": "8.15.9",
+    "@react-three/postprocessing": "^2.15.10",
+    "@react-three/rapier": "^1.1.2",
+    "@types/three": "^0.158.1",
+    "@types/uuid": "^9.0.6",
+    "@uiw/react-md-editor": "3.25.2",
+    "@vanilla-extract/babel-plugin": "^1.2.0",
+    "@vanilla-extract/css": "^1.13.0",
+    "@vanilla-extract/css-utils": "^0.1.3",
+    "@vanilla-extract/dynamic": "^2.0.3",
+    "@vanilla-extract/next-plugin": "^2.3.1",
+    "@vanilla-extract/recipes": "^0.5.0",
+    "@vanilla-extract/sprinkles": "^1.6.1",
+    "@zeit/next-bundle-analyzer": "0.1.2",
+    "css-loader": "^6.8.1",
+    "gh-pages": "^6.1.0",
+    "lamina": "^1.1.23",
+    "leva": "0.9.35",
+    "lodash": "4.17.21",
+    "next-compose": "0.0.2",
+    "next-remove-imports": "1.0.12",
+    "node-fetch": "3.3.2",
+    "prettier": "^3.1.0",
+    "r3f-perf": "7.1.2",
+    "react": "^18.2.0",
+    "react-device-detect": "^2.2.3",
+    "react-dom": "^18.2.0",
+    "react-use-refs": "^1.0.1",
+    "three": "^0.158.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.37",
+    "@types/react-dom": "^18.2.15",
+    "@typescript-eslint/eslint-plugin": "^6.10.0",
+    "@typescript-eslint/parser": "^6.10.0",
+    "@vanilla-extract/vite-plugin": "^3.9.2",
+    "@vitejs/plugin-react-swc": "^3.5.0",
+    "eslint": "^8.53.0",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-react-refresh": "^0.4.4",
+    "path": "^0.12.7",
+    "typescript": "^5.2.2",
+    "vite": "^5.0.0"
+  },
+  "description": "Web 3D Character Controller and World Platform Library",
+  "main": "index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jigglypop/gaesup-world.git"
+  },
+  "keywords": [
+    "three.js",
+    "@react-three/fiber",
+    "@react-three/drei"
+  ],
+  "author": "jigglypop",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/jigglypop/gaesup-world/issues"
+  }
+}

package/src/gaesup/animation/actions.ts

@@ -0,0 +1,123 @@
+import { useAnimations, useKeyboardControls } from "@react-three/drei";
+import { useFrame } from "@react-three/fiber";
+import { RefObject, useContext, useEffect } from "react";
+import { animationTagType, groundRayType } from "../controller/type";
+import {
+  GaesupWorldContext,
+  GaesupWorldDispatchContext,
+} from "../stores/context/gaesupworld";
+
+export type playActionsType = {
+  outerGroupRef: RefObject<THREE.Group>;
+  groundRay: groundRayType;
+  isRider?: boolean;
+};
+
+export default function playActions({
+  outerGroupRef,
+  groundRay,
+  isRider,
+}: playActionsType) {
+  const { characterGltf, animations: characterAnimations } =
+    useContext(GaesupWorldContext);
+  const dispatch = useContext(GaesupWorldDispatchContext);
+  const { animations } = characterGltf;
+  const control = useKeyboardControls()[1]();
+  const { actions } = useAnimations(animations, outerGroupRef);
+
+  useEffect(() => {
+    characterAnimations.keyControl = control;
+    dispatch({
+      type: "update",
+      payload: {
+        animations: {
+          ...characterAnimations,
+        },
+      },
+    });
+  }, [control]);
+
+  const playAnimation = (tag: keyof animationTagType) => {
+    characterAnimations.current = tag;
+    dispatch({
+      type: "update",
+      payload: {
+        animations: {
+          ...characterAnimations,
+        },
+      },
+    });
+  };
+
+  const setAnimationName = (actions: {
+    [x: string]: THREE.AnimationAction | null;
+  }) => {
+    characterAnimations.animationNames = Object.assign(
+      characterAnimations.animationNames,
+      Object.keys(actions).reduce((acc, cur) => {
+        return {
+          ...acc,
+          [cur]: cur,
+        };
+      }, {})
+    );
+    dispatch({
+      type: "update",
+      payload: {
+        animations: {
+          ...characterAnimations,
+        },
+      },
+    });
+  };
+
+  const resetAni = () => playAnimation("idle");
+  const playIdle = () => playAnimation("idle");
+  const playWalk = () => playAnimation("walk");
+  const playRun = () => playAnimation("run");
+  const playJump = () => playAnimation("jump");
+  const playFall = () => playAnimation("fall");
+  const playRide = () => playAnimation("ride");
+
+  useEffect(() => {
+    return () => {
+      resetAni();
+    };
+  }, []);
+
+  useEffect(() => {
+    // Play animation
+    const action = actions[characterAnimations.current]
+      ?.reset()
+      .fadeIn(0.2)
+      .play();
+    setAnimationName(actions);
+    return () => {
+      action?.fadeOut(0.2);
+    };
+  }, [characterAnimations.current]);
+
+  const { states, activeState } = useContext(GaesupWorldContext);
+  const { isNotMoving, isMoving, isJumping, isRunning, isAnimationOuter } =
+    states;
+  useFrame(() => {
+    if (isRider) {
+      playRide();
+    } else {
+      if (!isAnimationOuter) {
+        if (isJumping) {
+          playJump();
+        } else if (isNotMoving) {
+          playIdle();
+        } else if (isRunning) {
+          playRun();
+        } else if (isMoving) {
+          playWalk();
+        }
+        if (groundRay.hit === null && activeState.velocity.y < 0) {
+          playFall();
+        }
+      }
+    }
+  });
+}

package/src/gaesup/camera/cameraCollisionDetecter.tsx

@@ -0,0 +1,53 @@
+import { propType } from "../controller/type";
+
+export default function cameraCollisionDetector(prop: propType) {
+  //   const { cameraRay, constant, options } = prop;
+  //   const { camera } = useThree();
+  const checkCollision = (delta: number) => {
+    //     cameraRay.origin.copy(cameraRay.pivot.position);
+    //     camera.getWorldPosition(cameraRay.position);
+    //     cameraRay.dir.subVectors(cameraRay.position, cameraRay.pivot.position);
+    //     cameraRay.intersects = cameraRay.rayCast!.intersectObjects(
+    //       Object.values(cameraRay.intersectObjectMap)
+    //     );
+    //     if (
+    //       cameraRay.intersects.length &&
+    //       cameraRay.intersects[0].distance <= -constant.cameraInitDistance
+    //     ) {
+    //       if (options.cameraCollisionType === "transparent") {
+    //         cameraRay.intersetesAndTransParented = [...cameraRay.intersects];
+    //         cameraRay.intersetesAndTransParented.map((intersect) => {
+    //           const mesh = intersect.object as THREE.Mesh;
+    //           const material = mesh.material as THREE.MeshStandardMaterial;
+    //           material.opacity = 0.2;
+    //           material.transparent = true;
+    //         });
+    //       } else if (options.cameraCollisionType === "closeUp") {
+    //         constant.cameraMinDistance =
+    //           -cameraRay.intersects[0].distance * constant.cameraCollisionOff < -0.7
+    //             ? -cameraRay.intersects[0].distance * constant.cameraCollisionOff
+    //             : -0.7;
+    //       }
+    //     } else {
+    //       if (options.cameraCollisionType === "transparent") {
+    //         cameraRay.intersetesAndTransParented.map((intersect) => {
+    //           const mesh = intersect.object as THREE.Mesh;
+    //           const material = mesh.material as THREE.MeshStandardMaterial;
+    //           material.opacity = 1;
+    //           material.transparent = false;
+    //         });
+    //         cameraRay.intersetesAndTransParented = [];
+    //       }
+    //       constant.cameraMinDistance = constant.cameraInitDistance;
+    //     }
+    //     cameraRay.lerpingPoint.set(
+    //       cameraRay.followCamera.position.x,
+    //       constant.cameraMinDistance * Math.sin(-cameraRay.followCamera.rotation.x),
+    //       constant.cameraMinDistance * Math.cos(-cameraRay.followCamera.rotation.x)
+    //     );
+    //
+    //     cameraRay.followCamera.position.lerp(cameraRay.lerpingPoint, delta * 4);
+  };
+
+  return { checkCollision };
+}

package/src/gaesup/camera/control/map.ts

@@ -0,0 +1,10 @@
+import { cameraPropType } from "../../physics/type";
+
+export default function mapControl(prop: cameraPropType) {
+  const {
+    state,
+    worldContext: { activeState },
+  } = prop;
+  const position = activeState.position.clone();
+  state.camera.position.set(-10, 10, -10).add(position);
+}

package/src/gaesup/camera/control/normal copy.ts

@@ -0,0 +1,19 @@
+import { cameraPropType } from "../../physics/type";
+
+export default function normal(prop: cameraPropType) {
+  const {
+    state,
+    cameraRay,
+    constant,
+    checkCollision,
+    delta,
+    worldContext: { activeState },
+  } = prop;
+  cameraRay.pivot.position.lerp(
+    activeState.position,
+    1 - Math.exp(-constant.cameraCamFollow * delta)
+  );
+  state.camera.position.set(0, 0, 0);
+  state.camera.lookAt(cameraRay.pivot.position);
+  checkCollision(delta);
+}

package/src/gaesup/camera/control/normal.ts

@@ -0,0 +1,15 @@
+import { cameraPropType } from "../../physics/type";
+import { V3 } from "../../utils/vector";
+
+export default function normal(prop: cameraPropType) {
+  const {
+    state,
+    controllerContext: { perspectiveCamera },
+    worldContext: { activeState },
+  } = prop;
+  const cameraPosition = activeState.position
+    .clone()
+    .add(V3(perspectiveCamera.XZDistance, perspectiveCamera.YDistance, 0));
+  state.camera.position.lerp(cameraPosition, 1);
+  state.camera.lookAt(activeState.position);
+}

package/src/gaesup/camera/control/orbit.ts

@@ -0,0 +1,31 @@
+import { quat } from "@react-three/rapier";
+import { cameraPropType } from "../../physics/type";
+import { V3 } from "../../utils/vector";
+
+export default function orbit(prop: cameraPropType) {
+  const {
+    state,
+    controllerContext: { perspectiveCamera },
+    worldContext: { activeState },
+  } = prop;
+  const cameraPosition = activeState.position.clone().add(
+    V3(Math.sin(activeState.euler.y), 0, Math.cos(activeState.euler.y))
+      .normalize()
+      .clone()
+      .multiplyScalar(perspectiveCamera.XZDistance)
+      .multiplyScalar(perspectiveCamera.isFront ? -1 : 1)
+      .add(V3(0, perspectiveCamera.YDistance, 0))
+  );
+
+  state.camera.position.lerp(cameraPosition, 0.2);
+  state.camera.quaternion.copy(
+    activeState.quat
+      .clone()
+      .multiply(
+        perspectiveCamera.isFront
+          ? quat().setFromAxisAngle(V3(0, 1, 0), Math.PI)
+          : quat()
+      )
+  );
+  state.camera.lookAt(activeState.position);
+}

package/src/gaesup/camera/index.tsx

@@ -0,0 +1,102 @@
+import {
+  MapControls,
+  OrbitControls,
+  OrthographicCamera,
+  PerspectiveCamera,
+} from "@react-three/drei";
+import { useFrame, useThree } from "@react-three/fiber";
+import { useContext } from "react";
+import * as THREE from "three";
+import { propType, refsType } from "../controller/type";
+import { cameraPropType } from "../physics/type";
+import { GaesupControllerContext } from "../stores/context/controller";
+import { GaesupWorldContext } from "../stores/context/gaesupworld";
+import cameraCollisionDetector from "./cameraCollisionDetecter";
+import mapControl from "./control/map";
+import normal from "./control/normal copy";
+import orbit from "./control/orbit";
+
+export default function Camera({
+  refs,
+  prop,
+  control,
+}: {
+  refs: refsType;
+  prop: propType;
+  control: {
+    [key: string]: boolean;
+  };
+}) {
+  const worldContext = useContext(GaesupWorldContext);
+  const controllerContext = useContext(GaesupControllerContext);
+  const { cameraMode, perspectiveCamera, orthographicCamera } =
+    controllerContext;
+  const { rigidBodyRef, outerGroupRef } = refs;
+  const { cameraRay } = prop;
+  const { checkCollision } = cameraCollisionDetector(prop);
+  const { scene, camera } = useThree();
+  const { activeState } = worldContext;
+
+  const intersectObjectMap: { [uuid: string]: THREE.Object3D } = {};
+  const cameraProp: cameraPropType = {
+    ...prop,
+    checkCollision,
+    control,
+    controllerContext,
+    worldContext,
+  };
+
+  const getMeshs = (object: THREE.Object3D) => {
+    if (object.userData && object.userData.intangible) return;
+    if (
+      object instanceof THREE.Mesh &&
+      object.geometry.type !== "InstancedBufferGeometry"
+    ) {
+      intersectObjectMap[object.uuid] = object;
+    }
+    object.children.forEach((child) => {
+      getMeshs(child);
+    });
+  };
+
+  useFrame((state, delta) => {
+    if (
+      !rigidBodyRef ||
+      !rigidBodyRef.current ||
+      !outerGroupRef ||
+      !outerGroupRef.current
+    )
+      return null;
+    cameraProp.state = state;
+    cameraProp.delta = delta;
+
+    if (cameraMode.cameraType === "perspective") {
+      scene.children.forEach((child) => getMeshs(child));
+      cameraRay.intersectObjectMap = intersectObjectMap;
+      if (cameraMode.controlType === "orbit") {
+        orbit(cameraProp);
+      } else if (cameraMode.controlType === "normal") {
+        normal(cameraProp);
+      }
+    } else if (cameraMode.cameraType === "orthographic") {
+      mapControl(cameraProp);
+    }
+  });
+
+  return (
+    <>
+      {cameraMode.cameraType === "perspective" && (
+        <>
+          <OrbitControls target={activeState.position} />
+          <PerspectiveCamera makeDefault {...perspectiveCamera} />
+        </>
+      )}
+      {cameraMode.cameraType === "orthographic" && (
+        <>
+          <MapControls target={activeState.position} />
+          <OrthographicCamera makeDefault {...orthographicCamera} />
+        </>
+      )}
+    </>
+  );
+}

package/src/gaesup/camera/type.ts

@@ -0,0 +1,17 @@
+export type cameraRayType = {
+  origin: THREE.Vector3;
+  hit: THREE.Raycaster;
+  rayCast: THREE.Raycaster | null;
+  lerpingPoint: THREE.Vector3;
+  length: number;
+  dir: THREE.Vector3;
+  position: THREE.Vector3;
+  followCamera: THREE.Object3D;
+  pivot: THREE.Object3D;
+  intersetesAndTransParented: THREE.Intersection<
+    THREE.Object3D<THREE.Object3DEventMap>
+  >[];
+  intersects: THREE.Intersection<THREE.Object3D<THREE.Object3DEventMap>>[];
+  intersectObjects: THREE.Object3D[];
+  intersectObjectMap: { [uuid: string]: THREE.Object3D };
+};

package/src/gaesup/component/Airplane.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+import { propType, refsType } from "../controller/type";
+import calculation from "../physics";
+import { AirplaneInnerGroupRef } from "./gltf/AirplaneGltf";
+import {
+  AirplaneCollider,
+  AirplaneGroup,
+  AirplaneRigidBody,
+} from "./ref/airplane";
+
+export function Airplane({
+  controllerProps,
+  refs,
+}: {
+  controllerProps: propType;
+  refs: refsType;
+}) {
+  const { rigidBodyRef, outerGroupRef, capsuleColliderRef, innerGroupRef } =
+    refs;
+  calculation(controllerProps);
+
+  return (
+    <>
+      <AirplaneGroup ref={outerGroupRef}>
+        <AirplaneRigidBody
+          ref={rigidBodyRef}
+          groundRay={controllerProps.groundRay}
+        >
+          <AirplaneCollider prop={controllerProps} ref={capsuleColliderRef} />
+          {/* <CharacterGltf
+            gltf={characterGltf}
+            prop={prop}
+            url={props.url}
+            character={props.character}
+            groundRay={prop.groundRay}
+            refs={refs}
+            callbacks={callbacks}
+            isRider={true}
+          /> */}
+          <AirplaneInnerGroupRef ref={innerGroupRef} />
+        </AirplaneRigidBody>
+      </AirplaneGroup>
+    </>
+  );
+}

package/src/gaesup/component/Character.tsx

@@ -0,0 +1,48 @@
+"use client";
+
+import calculation from "../physics";
+
+import { propType, refsType } from "../controller/type";
+import CharacterGltf from "./gltf/CharacterGltf";
+import {
+  CharacterCapsuleCollider,
+  CharacterGroup,
+  CharacterRigidBody,
+  CharacterSlopeRay,
+} from "./ref/character";
+
+export function Character({
+  controllerProps,
+  refs,
+}: {
+  controllerProps: propType;
+  refs: refsType;
+}) {
+  const { capsuleColliderRef, rigidBodyRef, outerGroupRef, slopeRayOriginRef } =
+    refs;
+  calculation(controllerProps);
+
+  return (
+    <CharacterRigidBody ref={rigidBodyRef} controllerProps={controllerProps}>
+      <CharacterCapsuleCollider
+        prop={controllerProps}
+        ref={capsuleColliderRef}
+      />
+      <CharacterGroup ref={outerGroupRef}>
+        <CharacterSlopeRay
+          slopeRay={controllerProps.slopeRay}
+          groundRay={controllerProps.groundRay}
+          ref={slopeRayOriginRef}
+        />
+        {controllerProps.children}
+        <CharacterGltf
+          prop={controllerProps}
+          groupProps={controllerProps.groupProps}
+          groundRay={controllerProps.groundRay}
+          refs={refs}
+          callbacks={controllerProps.callbacks}
+        />
+      </CharacterGroup>
+    </CharacterRigidBody>
+  );
+}

package/src/gaesup/component/Vehicle.tsx

@@ -0,0 +1,40 @@
+"use client";
+
+import { propType, refsType } from "../controller/type";
+import calculation from "../physics";
+import CharacterGltf from "./gltf/CharacterGltf";
+import VehicleGltf from "./gltf/VehicleGltf";
+import { Wheels } from "./gltf/WheelJoint";
+import { VehicleCollider, VehicleGroup, VehicleRigidBody } from "./ref/vehicle";
+
+export function Vehicle({
+  controllerProps,
+  refs,
+}: {
+  controllerProps: propType;
+  refs: refsType;
+}) {
+  const { rigidBodyRef, outerGroupRef } = refs;
+  calculation(controllerProps);
+
+  return (
+    <VehicleGroup ref={outerGroupRef}>
+      <VehicleRigidBody
+        ref={rigidBodyRef}
+        groundRay={controllerProps.groundRay}
+      >
+        <VehicleCollider />
+        <CharacterGltf
+          prop={controllerProps}
+          groupProps={controllerProps.groupProps}
+          groundRay={controllerProps.groundRay}
+          refs={refs}
+          callbacks={controllerProps.callbacks}
+          isRider={true}
+        />
+        <VehicleGltf />
+      </VehicleRigidBody>
+      <Wheels prop={controllerProps} />
+    </VehicleGroup>
+  );
+}