{"id":17250070,"url":"https://github.com/stephengold/garrett","last_synced_at":"2025-04-14T05:32:16.586Z","repository":{"id":46876167,"uuid":"285431472","full_name":"stephengold/Garrett","owner":"stephengold","description":"A collection of camera controllers for JMonkeyEngine","archived":false,"fork":false,"pushed_at":"2025-04-09T21:36:15.000Z","size":797,"stargazers_count":11,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-09T22:29:29.302Z","etag":null,"topics":["camera-controllers","java","jme3","jmonkeyengine","jmonkeyengine3","jvm-library","library","open-source","orbit"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stephengold.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-06T00:09:29.000Z","updated_at":"2025-04-09T21:36:18.000Z","dependencies_parsed_at":"2023-02-16T02:30:30.764Z","dependency_job_id":"1a3d8c89-5d76-4111-ae54-0ab5809c4e02","html_url":"https://github.com/stephengold/Garrett","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephengold%2FGarrett","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephengold%2FGarrett/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephengold%2FGarrett/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephengold%2FGarrett/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stephengold","download_url":"https://codeload.github.com/stephengold/Garrett/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248826800,"owners_count":21167751,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["camera-controllers","java","jme3","jmonkeyengine","jmonkeyengine3","jvm-library","library","open-source","orbit"],"created_at":"2024-10-15T06:46:05.686Z","updated_at":"2025-04-14T05:32:16.201Z","avatar_url":"https://github.com/stephengold.png","language":"Java","readme":"# Garrett Project\n\n[The Garrett Project][garrett] provides a collection of camera controllers for\n[the jMonkeyEngine (JME) game engine][jme].\n\nIt contains 2 subprojects:\n\n1. GarrettLibrary: the Garrett runtime library\n2. GarrettExamples: example applications using the library\n\nComplete source code (in [Java]) is provided under\n[a 3-clause BSD license][license].\n\n\n\u003ca name=\"toc\"\u003e\u003c/a\u003e\n\n## Contents of this document\n\n+ [Important features](#features)\n+ [How to add Garrett to an existing project](#add)\n+ [How to build Garrett from source](#build)\n+ [Conventions](#conventions)\n+ [An overview of the example applications](#examples)\n+ [Acknowledgments](#acks)\n\n\n\u003ca name=\"features\"\u003e\u003c/a\u003e\n\n## Important features\n\n + `AffixedCamera`: affixes a camera to a rigid body at a specific offset.\n  The controlled camera moves with the rigid body as it translates and rotates.\n\n + `DynamicCamera`: a physics-based, 6 degree-of-freedom camera controller.\n  The controlled camera is enclosed in a spherical rigid body\n  that prevents it from penetrating other bodies.\n\n + `OrbitCamera`: a physics-based, 4 degree-of-freedom camera controller.\n  The controlled camera orbits a specified target,\n  optionally clipping or jumping forward\n  to maintain a clear line of sight in the target's CollisionSpace.\n  A continuum of chasing behaviors is implemented.\n\n[Jump to the table of contents](#toc)\n\n\n\u003ca name=\"add\"\u003e\u003c/a\u003e\n\n## How to add Garrett to an existing project\n\nGarrett comes pre-built as a single JVM library\nthat depends on [Minie].\nHowever, the Minie dependency is intentionally omitted from Garrett's POM\nso developers can specify *which* Minie library should be used.\n\nFor projects built using [Maven] or [Gradle], it is\n*not* sufficient to specify the\ndependency on Garrett.\nYou must also explicitly specify the Minie dependency.\nThe following examples specify \"+big4\",\nbut \"+debug\" or the default Minie library should also work.\n\n### Gradle-built projects\n\nAdd to the project’s \"build.gradle\" or \"build.gradle.kts\" file:\n\n    repositories {\n        mavenCentral()\n    }\n    dependencies {\n        implementation(\"com.github.stephengold:Garrett:0.5.3\")\n        implementation(\"com.github.stephengold:Minie:8.1.0+big4\")\n    }\n\nFor some older versions of Gradle,\nit's necessary to replace `implementation` with `compile`.\n\n### Maven-built projects\n\nAdd to the project’s \"pom.xml\" file:\n\n    \u003crepositories\u003e\n      \u003crepository\u003e\n        \u003cid\u003emvnrepository\u003c/id\u003e\n        \u003curl\u003ehttps://repo1.maven.org/maven2/\u003c/url\u003e\n      \u003c/repository\u003e\n    \u003c/repositories\u003e\n\n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.github.stephengold\u003c/groupId\u003e\n      \u003cartifactId\u003eGarrett\u003c/artifactId\u003e\n      \u003cversion\u003e0.5.3\u003c/version\u003e\n    \u003c/dependency\u003e\n\n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.github.stephengold\u003c/groupId\u003e\n      \u003cartifactId\u003eMinie\u003c/artifactId\u003e\n      \u003cversion\u003e8.1.0+big4\u003c/version\u003e\n    \u003c/dependency\u003e\n\n[Jump to the table of contents](#toc)\n\n\n\u003ca name=\"build\"\u003e\u003c/a\u003e\n\n## How to build Garrett from source\n\n1. Install a [Java Development Kit (JDK)][adoptium],\n   if you don't already have one.\n2. Point the `JAVA_HOME` environment variable to your JDK installation:\n   (In other words, set it to the path of a directory/folder\n   containing a \"bin\" that contains a Java executable.\n   That path might look something like\n   \"C:\\Program Files\\Eclipse Adoptium\\jdk-17.0.3.7-hotspot\"\n   or \"/usr/lib/jvm/java-17-openjdk-amd64/\" or\n   \"/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home\" .)\n  + using Bash or Zsh: `export JAVA_HOME=\"` *path to installation* `\"`\n  + using [Fish]: `set -g JAVA_HOME \"` *path to installation* `\"`\n  + using Windows Command Prompt: `set JAVA_HOME=\"` *path to installation* `\"`\n  + using PowerShell: `$env:JAVA_HOME = '` *path to installation* `'`\n3. Download and extract the Garrett source code from GitHub:\n  + using [Git]:\n    + `git clone https://github.com/stephengold/Garrett.git`\n    + `cd Garrett`\n    + `git checkout -b latest 0.5.3`\n  + using a web browser:\n    + browse to [the latest release][latest]\n    + follow the \"Source code (zip)\" link\n    + save the ZIP file\n    + extract the contents of the saved ZIP file\n    + `cd` to the extracted directory/folder\n4. Run the [Gradle] wrapper:\n  + using Bash or Fish or PowerShell or Zsh: `./gradlew build`\n  + using Windows Command Prompt: `.\\gradlew build`\n\nAfter a successful build,\nMaven artifacts will be found in \"GarrettLibrary/build/libs\".\n\nYou can install the artifacts to your local Maven repository:\n+ using Bash or Fish or PowerShell or Zsh: `./gradlew install`\n+ using Windows Command Prompt: `.\\gradlew install`\n\nYou can restore the project to a pristine state:\n+ using Bash or Fish or PowerShell or Zsh: `./gradlew clean`\n+ using Windows Command Prompt: `.\\gradlew clean`\n\n[Jump to the table of contents](#toc)\n\n\n\u003ca name=\"conventions\"\u003e\u003c/a\u003e\n\n## Conventions\n\nLibrary classes are in the `com.github.stephengold.garrett` package.\nExample classes are in the `com.github.stephengold.garrett.examples` package.\n\nThe source code and pre-built libraries are compatible with JDK 8.\n\n[Jump to the table of contents](#toc)\n\n\n\u003ca name=\"examples\"\u003e\u003c/a\u003e\n\n## An overview of the example applications\n\nApplications have been created to test and demonstrate\ncertain features of Garrett.\nThe following apps are found in the GarrettExamples subproject:\n\n### HelloGarrett\n\nA very simple example of how Garrett maps keys to input signals.\nUsing `AffixedCamera`, the camera stays at a fixed offset from the red sphere.\n\n+ \"W\" key, up-arrow key, equals key, plus key, or mouse wheel to zoom in\n+ \"S\" key, down-arrow key, hyphen key, minus key, or mouse wheel to zoom out\n\n### HelloDynaCam\n\nAn example of a camera controlled by `DynamicCamera`.\n\n+ move the mouse to rotate the camera in \"point-to-look\" mode\n+ equals key, plus key, or mouse wheel to zoom in\n+ hyphen key, minus key, or mouse wheel to zoom out\n+ \"W\" key to move the camera forward\n+ \"S\" key to move the camera backward\n+ left-arrow key or \"A\" key to strafe left\n+ right-arrow key or \"D\" key to strafe right\n+ \"Q\" key to raise the camera along the world's Y axis\n+ \"Z\" key to lower the camera along the world's Y axis\n+ up-arrow key to move the camera upward in view coordinates\n+ down-arrow key to move the camera downward in view coordinates\n+ hold down the \"G\" key for \"ghost mode\", which temporarily disables physics\n+ hold down the \"R\" key for \"ram mode\", which temporarily increase the mass\n+ hold down the left shift key to tempararily disable point-to-look mode\n\n### HelloOrbitCam\n\nAn example of a camera controlled by `OrbitCamera`.\nThe camera orbits the red ball, which is its target.\n\n+ drag with the left mouse button (LMB) to orbit the ball on 2 axes\n+ equals key, plus key, or mouse wheel to zoom in\n+ hyphen key, minus key, or mouse wheel to zoom out\n+ \"W\" key to move the camera forward (toward the ball)\n+ \"S\" key to move the camera backward (away from the ball)\n+ left-arrow key or \"A\" key to orbit left (counter-clockwise, seen from above)\n+ right-arrow key or \"D\" key to orbit right (clockwise, seen from above)\n+ \"Q\" key to orbit upward\n+ \"Z\" key to orbit downward\n+ hold down the \"X\" key for \"X-ray mode\", which temporarily ignores obstructions\n\n[Jump to the table of contents](#toc)\n\n\n\u003ca name=\"acks\"\u003e\u003c/a\u003e\n\n## Acknowledgments\n\nLike most projects, the Garrett Project builds on the work of many who\nhave gone before.  I therefore acknowledge the creators of (and contributors to)\nthe following software:\n\n+ the [Checkstyle] tool\n+ the [Git] revision-control system and GitK commit viewer\n+ the [GitKraken] client\n+ the [Firefox] web browser\n+ the [Gradle] build tool\n+ the [Java] compiler, standard doclet, and runtime environment\n+ [jMonkeyEngine][jme] and the jME3 Software Development Kit\n+ the [Linux Mint][mint] operating system\n+ [LWJGL], the Lightweight Java Game Library\n+ the [Markdown] document-conversion tool\n+ the [Meld] visual merge tool\n+ Microsoft Windows\n+ the [NetBeans] integrated development environment\n\nI am grateful to [GitHub] and [Sonatype]\nfor providing free hosting for this project\nand many other open-source projects.\n\nI'm also grateful to my dear Holly, for keeping me sane.\n\nIf I've misattributed anything or left anyone out, please let me know, so I can\ncorrect the situation: sgold@sonic.net\n\n[Jump to the table of contents](#toc)\n\n\n[adoptium]: https://adoptium.net/releases.html \"Adoptium Project\"\n[ant]: https://ant.apache.org \"Apache Ant Project\"\n[bsd3]: https://opensource.org/licenses/BSD-3-Clause \"3-Clause BSD License\"\n[checkstyle]: https://checkstyle.org \"Checkstyle\"\n[firefox]: https://www.mozilla.org/en-US/firefox \"Firefox\"\n[fish]: https://fishshell.com/ \"Fish command-line shell\"\n[garrett]: https://github.com/stephengold/Garrett \"Garrett Project\"\n[git]: https://git-scm.com \"Git\"\n[github]: https://github.com \"GitHub\"\n[gitkraken]: https://www.gitkraken.com \"GitKraken client\"\n[gradle]: https://gradle.org \"Gradle Project\"\n[java]: https://en.wikipedia.org/wiki/Java_(programming_language) \"Java programming language\"\n[jme]: https://jmonkeyengine.org \"jMonkeyEngine Project\"\n[latest]: https://github.com/stephengold/Garrett/releases/latest \"latest release\"\n[license]: https://github.com/stephengold/Garrett/blob/master/LICENSE \"Garrett license\"\n[lwjgl]: https://www.lwjgl.org \"Lightweight Java Game Library\"\n[markdown]: https://daringfireball.net/projects/markdown \"Markdown Project\"\n[maven]: https://maven.apache.org \"Maven Project\"\n[meld]: https://meldmerge.org \"Meld merge tool\"\n[minie]: https://stephengold.github.io/Minie/minie/overview.html \"Minie Project\"\n[mint]: https://linuxmint.com \"Linux Mint Project\"\n[netbeans]: https://netbeans.org \"NetBeans Project\"\n[sonatype]: https://www.sonatype.com \"Sonatype\"\n[utilities]: https://github.com/stephengold/jme3-utilities \"Jme3-utilities Project\"\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephengold%2Fgarrett","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstephengold%2Fgarrett","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephengold%2Fgarrett/lists"}