Install FireVoxel
=================

.. contents::
   :depth: 1
   :local:
   :backlinks: none

.. sidebar:: Download FireVoxel

   `Download from FireVoxel.org <https://www.firevoxel.org/download/>`_


.. _sysreqs:

System Requirements
-------------------

FireVoxel runs on 64-bit versions of Windows (Windows 7 and newer).
Windows XP and 32-bit Windows are not supported.

FireVoxel requires two **Microsoft Visual C++ redistributable packages**
that can be accessed via `Microsoft Visual C++ support page`_
and installed anywhere on your computer:

#. **Redistributable for Visual Studio 2015, 2017 and 2019**

       * On `Microsoft Visual C++ support page`_,
         scroll down to "Visual Studio 2015, 2017 and 2019"
         and download **x64:** :file:`vc_redist.x64.exe`.

#. **Redistributable for Visual Studio 2013**

       * On `Microsoft Update for Visual C++ 2013`_, select
         an appropriate mirror site and download :file:`vcredist_x64.exe`.

**Both of these packages are necessary.**
To check whether they are already installed on your computer,
go to Windows **Control Panel** > **Programs and Features**
and look for these packages on the list of currently installed programs.

.. _Microsoft Visual C++ support page: https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads

.. _Microsoft Update for Visual C++ 2013:
   https://support.microsoft.com/en-us/help/4032938/update-for-visual-c-2013-redistributable-package

.. _activate:

Download, Install, and Activate FireVoxel
-----------------------------------------

#. Download Firevoxel ``[build#].zip`` from `FireVoxel website <https://firevoxel.org/download/>`_.
   By downloading and installing this software, you agree to the terms
   of the FireVoxel `license <https://firevoxel.org/im/License_FireVoxel.pdf>`_.

#. Extract all files from ``[build#].zip`` into a folder named FireVoxel.
   **Do not install FireVoxel within Program Files.** Installing FireVoxel
   in Program Files may prevent FireVoxel from correctly addressing its subfolders.

#. If you already have a previously installed, working version of FireVoxel,
   extract the ``[build#].zip`` to the existing FireVoxel folder
   and overwrite the old files. Done!

#. If you never had FireVoxel installed on your computer before, navigate to the FireVoxel
   folder and double-click :file:`FireVoxel.exe` to open the software.

#. If you get an error message about a missing ``.dll`` or redistributable, close FireVoxel.
   Then download and install the two Microsoft Visual C++ redistributable packages listed
   in :ref:`sysreqs`.

   .. figure:: images/FV_Error_Redist2013Reqd.png
      :alt: Microsoft Visual C++ 2013 Redistributable is missing.
      :align: center
      :figclass: align-center

#. Run :file:`FireVoxel.exe` again.
   You will get an warning about missing :file:`FireVoxel.key`:

   .. figure:: images/FV_Error_NoKey.png
      :alt: FireVoxel key file not found. Specify exact location?
      :align: center
      :figclass: align-center

   Click :guilabel:`No`. You will see another message showing your
   **12- to 15-digit Computer ID**, also saved to the clipboard and
   ready to be pasted.

   .. figure:: images/FV_Error_NoKeyMachineID.png
      :alt: FireVoxel license not found.
      :align: center
      :figclass: align-center

#. Email your Computer ID number to **hr18@nyu.edu**.
   Use :kbd:`Ctrl` + :kbd:`V` to paste your Computer ID into the body of your message.
   Please do not send screenshot images. In the email, please also include **your name**,
   **your place of work or study**, and **a brief description of your project**
   for which you intend to use FireVoxel.

#. You will receive a reply email with a small file :file:`FireVoxel.key` as an attachment.
   Save this attachment in your FireVoxel folder. You are now ready to use FireVoxel.

#. Please download and install new builds as they become available.
   After you download a new ``[build#].zip``, extract it to your existing FireVoxel folder,
   overwriting the old files (:file:`FireVoxel.key` will not be overwritten).
   Alternatively, extract the new build into a new folder, copy or move :file:`FireVoxel.key`
   into this folder, delete the old FireVoxel folder, and rename the updated folder **FirVoxel**.