~swashberry/godot-license-dialog

813d8fd8ebcbefa1182ef7c8a72a78e60ef3345e — swashberry 2 months ago e273b92 master
add basic documentation.
A README.md => README.md +113 -0
@@ 0,0 1,113 @@
Godot Unofficial License Dialog
===============================

If, like me, you want to support open-source game engines like [Godot], but you
worry about displaying proper licensing information for any project you do
which includes third-party software, then this project is for you.  Software
licenses can be a real pain in the neck sometimes, and it would be a lot better
if it was easier to remain compliant with them.

The Godot Engine uses a lot of third-party modules and components which all use
slightly different software licenses and affect what licensing information you
need to include with any games or other projects you make.  If you build Godot
from source, this licensing information may change, as different platforms and
different configurations of the engine use different modules, and that means
your attribution notices need to adapt as well.

The Godot Unofficial License Dialog, or GUiLD for short, is a simple node for
Godot Engine projects which parses and displays licensing information for your
project in a convenient and human-readable format which your users can access
in-game.

How It Works
------------

[The Godot Engine][Godot] actually has functions built-in which can give you
the copyright and licensing information for the version of the Godot Engine you
use to build your project.  The Godot Engine pulls this information from a file
in [its source code repository][godot source], COPYRIGHT.txt, which the
compiler reads and then bakes into the game engine.  This file is written in
[a standard format][debian license file format] which is parsed by the compiler
to create the information you can pull from the engine.

The problem with obtaining licensing information in this way is that the data
it gives you still needs to be displayed in a clear and human-readable format.
As it stands, what the engine is giving you is arrays of dictionaries which
also contain arrays.

What GUiLD does is read in the licensing information from the engine and use
it to create a popup dialog which displays a list of buttons that the user can
press to view attribution notices and the full text of any license for any
third-party modules which the Godot Engine might be using.

As an extra feature, the popup dialog will also read copyright information for
_your_ project and display that in a separate list from the copyright
information for the Godot Engine, so that your software licenses can be easily
displayed and unambiguously separated from the licenses which the Godot Engine
is subject to.  In order to do this, you must create a COPYRIGHT.txt file
yourself.

A sample COPYRIGHT.txt file which displays the copyright information
for the Godot Unofficial License Dialog has been included in the source
repository which you can use as a reference, and a sample project has been
included which you can use to see the popup in action.

How To Use It
-------------

Before you do anything else, please read the [Disclaimer](#disclaimer) below to
make sure you fully understand what GUiLD does and does not do.

To use GUiLD in your project, copy the [license\_dialog.gd][script] and
[license\_dialog.tscn][scene] files into your Godot Engine project folder.
These files will give you a node named `LicenseDialog` which can be used as a
regular popup dialog that will display the licensing information for your
project.

For more details and further setup instructions, please [read the Getting
Started file][Getting Started] in the docs folder.

Disclaimer
----------

The Godot Unofficial License Dialog (GUiLD) **does not** check for
compatibility between licenses and **does not** guarantee that you will be
fully complaint with the licenses for any software you may be using in your
project.  YOU ARE SOLELY RESPONSIBLE FOR ENSURING THAT YOU ARE COMPLIANT WITH
THIRD-PARTY SOFTWARE LICENSES!

GUiLD **does not** include attribution notices or license texts automatically;
it only pulls this information from the Godot Engine and from information which
you yourself supply.  Please read the documentation carefully so you know what
you are doing.

Use of GUiLD in your project may not in itself be sufficient in order to remain
compliant with certain software licenses--some licenses will require more than
an attribution notice and/or inclusion of the full text of a license with the
software.  For example, copyleft licenses such as the [GNU General Public
Licenses][GPL] may require you to distribute your source code if you use
software released under such licenses.  Be sure to read the licenses for any
third-party materials carefully before using them in your project.

The author of this software is not affiliated with the Godot Engine project and
does not represent the Godot Engine project in any capacity; GUiLD is not
endorsed by the Godot Engine project.

THE AUTHOR AND CONTRIBUTORS OF THIS SOFTWARE ARE NOT LAWYERS AND ARE NOT
PROVIDING LEGAL ADVICE!  THE USE OF THIS SOFTWARE IN ANY PROJECT IS NOT
ENDORSED BY THE AUTHOR OR CONTRIBUTORS OF THIS SOFTWARE AND ITS EFFECTIVENESS
OR FUNCTIONALITY IS NOT GUARANTEED.

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

[Godot]: https://godotengine.org/
[godot source]: https://github.com/godotengine/godot/
[debian license file format]: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
[Getting Started]: docs/GETTING_STARTED.md
[GPL]: https://en.wikipedia.org/wiki/GNU_General_Public_License

A docs/.gdignore => docs/.gdignore +0 -0
A docs/GETTING_STARTED.md => docs/GETTING_STARTED.md +133 -0
@@ 0,0 1,133 @@
# Getting Started

This file will give you basic setup instructions so you can use the Godot
Unofficial License Dialog (GUiLD) in your game or other project.

It is recommended that you read this document in a Markdown reader or on the
project's [GitHub](https://github.com/swashdev/godot-license-dialog), as
it contains embedded images and hyperlinks which will provide you with visual
aids and additional information.

## Before Beginning

This documentation assumes you have a basic grasp on how to use the Godot Engine
editor.  If you don't know how to use the Godot Engine editor, I recommend you
read the [Godot Engine documentation](https://docs.godotengine.org/en/stable/).

## Basic Setup

<img style = "float:right" src = "screenshots/getting_started_01.png" title = "The FileSystem dock in a Godot Engine project, showing the file `license_dialog.gd` selected."/>

If you haven't already, start by downloading the project.  The only files you
really need are `license_dialog.gd` (the script file) and `license_dialog.tscn`
(the scene file for the `LicenseDialog` node) from the root folder.  Because
GUiLD is public domain software, it is not necessary to download
`COPYRIGHT.txt` or the `UNLICENSE` file, and the rest of the files in the
root folder are either documentation or part of the sample project.

Drop the files into your Godot Engine project folder.  Although you can place
them in any folder you wish, I recommend placing them in the same folder to
begin with.  If you want them to be in separate folders, move them into their
appropriate directories from within the Godot Engine editor by right-clicking
them in the FileSystem dock and clicking "Move To."  If you do it this way, the
Godot Engine will automatically fix references to the script file within the
`LicenseDialog` scene for you.

If you want to, you can now rename the script and scene files by
right-clicking them in the FileSystem dock and clicking "Rename."  This will
also automatically update references for you.  For the purposes of this
documentation, we will assume that the files are still named
`license_dialog.gd` and `license_dialog.tscn`.

### Setting Up Project Information

After you've got the scene and script files where you want them in your project
folders, it's time to give the `LicenseDialog` node any information it needs
about your project.

Open up the `license_dialog.tscn` file in the Godot Engine editor and look in
the Inspector dock.  By default, this dock will be in the upper-right in the
"Inspector" tab.  You'll notice that it says `LicenseDialog` at the top, the
default name for the root node of this scene.  You can rename it if you wish,
but for our purposes we'll assume you let it keep its default name.

<img style = "margin: 0 auto" src = "screenshots/getting_started_02.png" title = "The Inspector dock in a Godot Engine project, showing some fields the user can modify to customize a `LicenseDialog` node." />

Under "Script Variables" you'll see some variables which you can modify by
typing some values into some text boxes.

#### Project Name

This is the name of your project, which will be used to label buttons in the
`LicenseDialog` which show attribution information for your project.

If you leave this field blank, the `LicenseDialog` will use the name which is
stored in your project file, so you don't need to do anything here unless you
want the name of your project to be displayed differently in the list of
attribution notices than it would be normally.

#### Copyright File

This is a path which refers to a file storing copyright information for your
project.  The `LicenseDialog` will look for a file stored in this location which
contains all of the information it needs to display attribution notices and
license texts for your project (*not* the Godot Engine).

The file in question needs to be formatted in a specific way in order for the
`LicenseDialog` to read it properly.  More detailed information will be given in
future versions of this documentation, but for now you can use [the sample
COPYRIGHT.txt] included with GUiLD or [the Godot Engine's COPYRIGHT.txt] as a
reference, or refer to the format specification [here][Debian copyright file
format].

[the sample COPYRIGHT.txt]: ../COPYRIGHT.txt
[the Godot Engine's COPYRIGHT.txt]: https://github.com/godotengine/godot/blob/master/COPYRIGHT.txt
[Debian copyright file format]: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/

**Note:**
Strictly speaking, you don't _need_ to include a copyright file with your
project.  However, I recommend that you do so, especially if you are using
third-party assets in your project, as you can take advantage of GUiLD to
display licensing information for your project, including third-party assets,
as well as the Godot Engine.  
If you choose not to include a copyright file, leave the Copyright File variable
blank.  If you specify a file which does not exist, your project will spit out a
warning when it is run letting you know that the `LicenseDialog` could not find
it.

**Helpful Tip:**
If you choose not to include a copyright file, you can slim down your scripting
a lot by deleting the `_read_copyright_file` function and any references to it
from the `license_dialog.gd` file, as this is the longest function in that
script.


### Implementing the Popup

The `LicenseDialog` node is a node of type `WindowDialog`, a class that comes
packaged with the Godot Engine which is used to display popup windows.

To add the `LicenseDialog` to your project, add it to another node, perhaps
containing the main menu.  After this, you can show it to the user by simply
adding a button which causes the window to pop up.

Here's an example function from a main menu which is linked to the "pressed"
signal from a `Button` node:

```gdscript
# The "Legal Stuff" button has been pressed.  This will open a dialog box
# containing licensing information.
func _on_LegalStuffButton_pressed():
	$LicenseDialog.popup_centered()
```

You can find more information about the `WindowDialog` class by visiting its
page in [the Godot Engine documentation][WindowDialog].

[WindowDialog]: https://docs.godotengine.org/en/stable/classes/class_windowdialog.html

**Helpful Tip**:
You can change what type of node the `LicenseDialog` is by right-clicking it and
selecting "Change Type."  Note that if you do this you will also have to change
what class the script in `license_dialog.gd` will inherit from; otherwise it
will not work.

A docs/screenshots/getting_started_01.png => docs/screenshots/getting_started_01.png +0 -0
A docs/screenshots/getting_started_02.png => docs/screenshots/getting_started_02.png +0 -0