deploy: 56d996b

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 5a83443332613cb9bb2e90ff1181e1ba
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/adding_assets.rst.txt

@@ -0,0 +1,59 @@
+Asset Palette and Libraries
+============================
+
+The asset palette is the large panel on the right side of tthe AssetPlacer interface. This is where you manage your libraries and add and remove assets.
+To add assets, simply drag and drop them into the panel. Note, that only 3D scenes (i.e. .tscn files with a root node that is/extends Node3D), 3D models (e.g. .obj, .gltf files) and meshes are supported, since other resources cannot usefully be placed in the 3D world.
+The number of assets per library is unlimited. Yet, it is recommended to separate assets in libraries to make browsing more efficient.
+
+.. image:: images/DroppingAsset_v2.png
+
+If no library is open yet, a new one is created when you add the first asset. You can also create a new library by clicking the ``+`` button on the right side of the library tab bar. 
+You can save the library by clicking on the ``Save Library`` button. Libraries are per default stored in the ``user:://`` directory. 
+This has the advantage of not cluttering your project folder, but in return sharing your project folder does not include your libraries, so take this into account when making backups or using version control. 
+Alternatively, you can configure where libraries are saved in the :doc:`Project Settings <settings/>`.
+A saved library can be opened by clicking ``Load Library``. This opens the library in a new tab. If you want to close a library tab, simply click on it with the middle mouse button.
+You can also right click a library tab to open the context menu, to either locate it in your file explorer, or to save a copy of it.
+
+.. image:: images/LibraryContextMenu_v4.png
+
+If you want to browse through all of your assets in 3D (for example to see how they relate in size), you can click on ``Generate Asset Zoo``. An asset zoo is a scene where all the assets of the library are placed, such that you can browse through them in 3D.
+If you want to save the asset zoo, right click on the scene name and ``Save As``, as the zoo is only saved at a temporary location and will be overwritten.
+
+.. image:: images/AssetZoo.png
+
+If you want to remove an asset from a library, locate it in the FileSystem, or open it as a scene, you can right click it to open its context menu.
+
+.. image:: images/AssetContextMenu_v4.png
+
+You can also click on ``Dynamic Preview``, or press :kbd:`V` while hovering over it to get a 3D preview of your asset. Rotate the asset with your middle mouse button and if you want to update the thumbnail from the new perspective, hit :kbd:`Space`.
+
+.. image:: images/DynamicPreview.gif
+
+Libraries keep only references to the assets you added. If you move assets around or delete them, their references might become invalid, and you need to add the asset again.
+In case of unexpected behavior refer to the "Output" tab for information.
+
+You can filter assets, by using the searchbar between the library tab and the assets.
+
+.. image:: images/FilterAssets_v2.gif
+
+In case you would like to place more instances of an asset that is already in the scene, you can select an instance of this asset in the scene, and then press the "Match Selected" button. 
+This way, the matching asset will be selected in the current library, or in case that it is not present in the library, it will be selected.
+
+.. image:: images/MatchSelected_v2.gif
+
+Previews 
+----------
+
+The plugin automatically generates previews for your assets. It attempts to frame your asset as good as possible. However, you might want to change from which side your assets are being previewed. 
+You can either choose to view them from the top, the front, the left, the right, the bottom, or the back. The default perspective can be configured in the :doc:`Project Settings <settings/>`. 
+However, as you might want to choose differently for different assets, you can also choose the perspective per library in the right-click context menu of the tab bar, or by right clicking on an asset.
+The preview setting on an asset overrides the preview setting of the library, which overrides the one set in the ProjectSettings.
+
+.. image:: images/PreviewPerspectiveAsset_v2.png
+
+The priority of the settings is such, that the setting on the asset overrides the library, and the library overrides what is configured in the project settings. 
+
+.. image:: images/PreviewPerspectiveLibrary_v2.png
+
+There is also an option to reset the configuration on all assets of a library.
+In case your asset changed in some way, you can click "Reload Preview" in the right-click context menu of on an asset, or "Reload all Previews" in the context menu of a library. 

_sources/demo.rst.txt

@@ -0,0 +1,15 @@
+Demo
+=============
+
+An early version of this plugin is an artifact of my thesis "An Analysis of Level Design Tools and Development of a Godot 4 Plugin". In case you are interested in reading it, you can download it for free `here <https://drive.google.com/file/d/1mLH0y2ozTfkQ6tcTjn1u-QVynM5--yX6/view?usp=drive_link>`_. This version, with some minor updates and bugfixes, is freely available as a demo for you to download at https://github.com/CookieBadger/assetplacer-docs/releases/tag/Demo.
+
+.. image:: images/Thesis.png
+
+On how to install the plugin, see :doc:`Installation <installation/>`. As the demo is developed in C#, you need to use a Mono version of the Godot engine, and have `.NET <https://dotnet.microsoft.com/en-us/download/dotnet/6.0>`_ installed. Also, note that the plugin folder is called ``assetplacer_demo``, and its respective location ``res::/addons/assetplacer_demo``. 
+
+Using the demo
+-----------
+
+You may use this demo for evaluating the AssetPlacer's functionality before committing to a purchase. If you do not intend to purchase the full version, you may also use the demo for non-commercial purposes, such as personal projects, or to complement reading of the academic thesis "An Analysis of Level Design Tools and Development of a Godot 4 Plugin". 
+
+The demo will eventually release as open-source, but for now, please consider supporting my work by `purchasing the full version <https://cookiebadger.itch.io/assetplacer>`_ if you want to use in commercial projects.

_sources/faq.rst.txt

@@ -0,0 +1,95 @@
+Frequently Asked Questions (FAQ)
+================================
+
+.. |nbsp| unicode:: 0xA0 
+   :trim:
+
+Is there some trial or demo?
+----------------------------
+There is! The first AssetPlacer version was originally developed for an academic thesis, which you can check out `here <https://cookiebadger.itch.io/assetplacer#:~:text=87%20kB-,Development%20log>`_. 
+It includes a demo for the plugin, that was patched to fix bugs and support newer Godot versions.
+You can use this demo to see if the plugin works for you. By buying the full version you support my work and ensure that more updates will be developed in the future.
+
+Why is this not entirely free?
+------------------------
+
+We all love open-source software like Godot for its accessibility and the freedom it gives to users. We then make games with it, which are - in most cases - commercial. 
+Of course, game devlopers have fun while making games, in the best case, but they still have to pay their bills, thus charging for their work is perfectly valid. 
+Many commercial platforms for acquiring assets, such as 3D models exist as well, such that artists can be remunerated for their work, even though it should fit a general purpose. 
+
+This plugin is neither a game, nor does it contain assets for a game, but still months of development time have been spent to make it as useful as possible. 
+As gratification alone cannot buy any food or pay rent, this plugin is being given away for a small amount of money. 
+Considering the time you can save by using it, especially when using modular assets, it seems like a very fair price to me. 
+The plan is, to keep developing the plugin, by adding new features and maintaining compatibility with major engine versions. 
+As you receive the source code of the plugin directly, you are also free to make any changes as you see fit, if you ever need to change something. 
+Your freedom of use is as unlimited as I can make it, and as much as I would like to give the plugin away for free entirely, I am grateful for everybody who appreciates my work by buying it fairly.
+I might release other plugins as Open-Source in the future. Buying this plugin would also support my work in this endeavor.
+In case that you really do not want to pay for a tool, you can check out this `Open Source Alternative <https://github.com/Frontrider/Godot-Scene-Browser>`_ for Godot |nbsp| 3.
+
+I can only find the C# version. Where is GDScript?
+-----------------------------------------------------
+
+At the moment, this plugin is written in C# only. The choice to develop it in C# was made, because of the large amounts of code and the frequent use of abstraction and high-level language features. 
+This is much easer to handle with a powerful language with a powerful external IDE. As you might be aware, C# code can only be run in the Mono version of the Godot engine, which requires `.NET <https://dotnet.microsoft.com/en-us/download/dotnet/6.0>`_ to be installed, which might be annoying for some of you.
+I am sorry for this inconvenience. Maybe I will translate the plugin to GDScript eventually, but for now it is the way it is.
+
+
+Is there a way to use this plugin for 2D levels?
+-------------------------------------------------------
+
+Currently, the plugin only features tools for 3D levels, but I thought about adding tools for 2D as well. Separating the AssetPlacer into an AssetPlacer3D and a AssetPlacer2D (i.e. having two bottom panels) would be an option, that might be implemented in the future.
+
+
+.. 
+    My assets show no preview thumbails. What is wrong?
+    ------------------------------------------------------
+
+    This can happen sometimes, especially when you open a project for the first time on a different computer. If you want the preview for a .tscn file, then open the file and save it, this way the thumbnail is generated.
+    If you want to see the thumbnails of some 3D models, you have to reimport them (change them to be imported as a mesh and then back to import as a scene). 
+    Unfortunately, this requires restarting the editor at the moment, but if a more efficient alternative for this problem is found, I will try to implement it.
+
+Godot 3.x?
+-------------
+No, sorry.
+
+
+I added the plugin, but I cannot enable it!
+----------------------------------------------------------------------
+
+Make sure to press the "Build" button at the top right before you enable the plugin. If the button does not show up, create a new C# script in your project and delete it again. It should show up now. 
+Once you built the plugin without errors (check the build output), you should be able to enable it in the project settings.
+In case this does not fix a problem, make sure you followed the instructions in the :doc:`Installation page <installation/>`, and then  `create an issue on GitHub <https://github.com/CookieBadger/assetplacer-docs/issues/new>`_ or write a comment on `itch`_ describing your problem and I will do my best to help! 
+
+
+What can I use the source code for?
+----------------------------------------
+
+You bought the plugin, then you own it. You can modify the source code however you see fit, use it for any amount of projects on any number of machines. 
+If it somehow is of use to you, you may also use parts of the code inside any game you are making. 
+
+
+For how long will I be able to use the plugin? Will I receive updates?
+-------------------------------------------------------------------------------------
+
+There is no restriction to the usage, use it in any amount of projects for as long as you want! As long as the plugin is still in development, you will also receive accesss to any updates bringing new features, or compatibility with newer engine versions.
+
+
+I found an issue with the plugin. Where should I report it?
+---------------------------------------------------------------
+
+To report any errors or problems you might encounter using the plugin, please `create an issue on GitHub <https://github.com/CookieBadger/assetplacer-docs/issues/new>`_ describing the problem. In case you do not have a GitHub account, you can also write a comment on the `itch`_  page. 
+
+
+You should implement this and that! Also, I had an idea for another tool!
+--------------------------------------------------------------------------
+
+As described in the other answers, you can always `create an issue on GitHub <https://github.com/CookieBadger/assetplacer-docs/issues/new>`_ or comment on the `itch`_ page of the plugin. 
+Please take into account, however, that the focus of the development might lie in improving stability, and thus bugs will be prioritized over features. 
+Also, not every feature is feasible to implement, since this is a one man project, and requests might also be declined for features that might only serve a specific use case or a very limited amount of users.
+
+
+I made this level with the AssetPlacer!
+----------------------------------------
+Amazing! If you want to share what you have made, feel free to tag any of my social media accounts (e.g. `@_cookieBadger <https://twitter.com/_cookieBadger>`_ on Twitter) or post it as a comment on the `itch`_ page, since I'd be super interested in seeing what you made with it! 
+
+.. _itch: https://itch.io/t/3066159/levels-and-environments-youve-made-with-assetplacer

_sources/index.rst.txt

@@ -0,0 +1,63 @@
+.. AssetPlacer documentation master file, created by
+   sphinx-quickstart on Thu Mar 30 07:37:23 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to the AssetPlacer documentation!
+=====================================================
+
+The **AssetPlacer** is a plugin for the Godot game engine, that helps with level design by providing advanced asset browsing and placement tools.
+`Get it now on itch.io <https://cookiebadger.itch.io/assetplacer>`_!
+
+
+*If you like the plugin, and want to help me, please* `leave a review <https://cookiebadger.itch.io/assetplacer/rate>`_!
+
+.. image:: images/Screenshot2_v2.png
+
+
+.. toctree::
+   :hidden:
+   :maxdepth: 4
+   :caption: Quickstart
+
+   demo
+   installation
+   usage
+
+.. toctree::
+   :hidden:
+   :maxdepth: 4
+   :caption: Manual
+
+   interface
+   adding_assets
+   placing_assets
+   placement_modes
+   snapping
+   painting_orienting
+   settings
+
+.. toctree::
+   :hidden:
+   :maxdepth: 4
+   :caption: About
+
+   faq
+   license
+
+
+Not only can you save massive amounts of time using the AssetPlacer, it also helps you achieve the same things with fewer actions, thus you can get more done with less strain. 
+Do you want to see the plugin in action? Watch `this video <https://youtu.be/vkeYPDnk4DQ>`_, showing the creation of the scene above.
+
+Click on any topics on the sidebar to find more information. If you want to quickly get started, read through the :doc:`Installation <installation/>` and :doc:`Usage <usage/>` pages. 
+
+
+   .. If you want to see the asset placer in action, check out the following video: [Timelapse video]
+   .. There are also tutorials on how to use it: [Tutorial]
+
+
+.. image:: images/ItchBanner.png
+
+|
+
+.. _here: https://cookiebadger.itch.io/assetplacer

_sources/installation.rst.txt

@@ -0,0 +1,34 @@
+Installation
+=============
+
+The AssetPlacer is a paid plugin, therefore it is not available at Godot's built-in asset library. You can purchase the AssetPlacer plugin `here`_. 
+Not all versions of Godot are supported by the plugin, so make sure you check that the plugin is compatible with the version you intend to use before you make your purchase. 
+To install the plugin, follow the instructions below.
+
+The AssetPlacer is developed in C#. Hence, to use it, you need to use a Mono version of the Godot engine, and have `.NET <https://dotnet.microsoft.com/en-us/download/dotnet/6.0>`_ installed.
+
+1. Once purchased, retrieve and extract the downloadables. Make sure to choose the package that corresponds to your Godot version. 
+
+2. Move the assetplacer folder into the addons folder of the Godot project, where you intend to use the plugin, such that the path to the plugin contents are ``res::/addons/assetplacer``. If the addons folder does not exist yet, create it. Note that it has to be called "addons".
+
+.. image:: images/AssetPlacerFolder.png
+
+3. In the top right corner of the editor, next to the play buttons, click the "Build" button. If you are using Godot 4.2 or later, this button is to the left and has a hammer icon. Otherwise it is a button to the right that reads "Build".
+
+.. image:: images/BuildButton.png
+
+In case the button is not there, make sure you are using the Mono version of Godot, and press ``Project -> Tools -> C# -> Create C# solution``, or create a new C# script in your project and delete it again.
+
+4. Go to ``Project -> Project Settings -> Plugins`` and enable the AssetPlacer.
+
+.. image:: images/ProjectSettings.png
+
+5. On the bottom panel (next to Output, Animation, MSBuild, etc.), a new option "AssetPlacer" should have appeard. Click it, to open the AssetPlacer UI. 
+
+.. image:: images/AssetPlacerBottomPanel_v2.png
+
+Congratulations, you are ready to use the AssetPlacer!
+
+
+
+.. _here: https://cookiebadger.itch.io/assetplacer

_sources/interface.rst.txt

@@ -0,0 +1,28 @@
+Interface
+=========
+
+
+The AssetPlacer UI consists of two major components. On the right, there is the asset palette, containing all currently selected assets.
+On the left, there are the placement settings, to configure where assets should be placed in the scene tree and in the 3D world.
+In the following image, parts of the UI are highlighted and enumerated:
+
+.. image:: images/InterfaceLayoutFine_v2.png
+
+#. The asset pallete. Drag 3D scenes, or 3D models that are imported as scenes, from the FileSystem to this panel, to add them to the current library. Select an asset by clicking on it to enable placement in the scene.
+#. The asset filter/search bar to quickly find what you are looking for.
+#. The library tab bar. Switch between different asset libraries or create a new library here.
+#. If a node is selected, this button will create and/or select the corresponding asset in the palette.
+#. Preview thumbnail size slider.
+#. Save the current library or load an existing library into a new tab.
+#. Plugin Header. Shows the version, Help and About buttons, and a button to detach the AssetPlacer into an external window.
+#. Spawn hierarchy selector. Defines under which node the assets are being placed. Defaults to the scene root. Drag and drop a node from the scene tree into the selector to mark it as the parent node for placing assets. Alternatively, click the button next to it, to mark the currently selected node.
+#. Placement settings. Switch between plane placement mode and surface placement mode. Configure the plane, or alignment with surface normal. Contains a button to position the plane, such that the currently selected node is on the plane.
+#. Snapping settings. Contains a checkbox for enabling and disabling snapping. Configure the size of the snapping grid, or the fine grid when holding down the Shift key. Offset the grid from the origin. Contains a button to offset the grid, such that the currently selected node is on the grid.
+
+
+AssetPlacer on Separate Window
+-----------------------
+
+By pressing the detach button, you can make the AssetPlacer floating, i.e. use it in an external Window. This way, you can increase your workspace, if you are, for example, working with multiple monitors.
+
+.. image:: images/DetachWindow_v2.gif