Description

This plug-in is an attempt to add support for exchanging images between Excel xlsx file and Unity texture(sprite) assets. This plug-in is a bit tricky, read this article carefully to understand how it works. Exporting images to Excel is a relatively safe operation, but importing images from Excel file will rewrite your Unity assets. The package is tested with LibreOffice and Microsoft Excel, read comparison sections below.

Setup:

1. Import BGDatabase package (v. >= 1.8.11) and create your own database as described here
2. Import Excel plugin (v. >= 1.12)
3. Import this package
4. Enable image transferring in data source settings (read more about the settings )
5. [Important] Backup your project if you plan to import images from Excel file and backup your Excel file if you plan to export images to your existing Excel file
6. Run import and(or) export jobs and make sure all functions work as you expected. Check texture resolutions to make sure they are not scaled down (read more about Microsoft Excel below)

Limitations and restrictions

1. texture, texture2D and sprite fields are supported
2. for sprite field, the assets should have "Sprite Mode"="Single", multiple mode is not supported
3. jpeg and png formats are supported
4. xlsx Excel file format is supported. Currently, there is no support for older xls format
5. Image and reference modes are not compatible. File, created with images, should not be imported with "Reference" mode, otherwise reference values will be erased.
6. Importing images is a destructive operation. With regular data importing, there is an option to revert all changes by pressing on "Reload" button. While importing images, existing Unity textures will be rewritten without an option to roll back the changes.

How image transferring works

By default, Unity asset field values are passed as string references. String reference is an address, which can be used to load the asset in runtime. For image fields, there is an option to pass the image itself instead of its address.

While exporting, database uses image references (string values) to find and read Unity assets (textures) and creates corresponding images in Excel file. Images are floating on top of the cells and anchors are used to "link" an image to the target cell. Before writing images to Excel file, all existing images, "linked" to the same cells are deleted.

While importing Database read images from Excel file and uses image references to find and re-write target Unity assets. Back up your project before trying to import data for the first time. Every time you import images from Excel file, the Unity assets are rewritten with images from Excel file. You need to ensure that images inside Excel file are not compressed and have original resolution (read Microsoft Excel vs LibreOffice section for more details)

Settings

To enable images transfer, navigate to your data source and toggle on "Enable" parameter under "Images" tab and

1. Option #1: Enable "Transfer images" under "Default parameters". Default parameters affect all compatible fields
2. Option #2: Enable "Transfer images" under "Fields" for certain field(s). Field parameters override default parameters, the final status is shown under "S" column

It can occur during picture import that some cell values are invalid or not set. Invalid values may have different image format or in case of the sprite fields, value may reference a sprite from texture with multiple sprites mode. In this case it's not possible to overwrite existing asset, and you may choose to skip the image or create a new asset.

In case you want to create new assets, you need to

1. Select a folder for new assets. For the fields with Resources loader, this folder should be under Resources folder or Resources folder itself. For the fields with Addressables loader, this folder should be included into Addressables settings.
2. While adding new assets, you may also want to save database after importing. There is an option to revert the changes, by clicking on "Reload" button, but assets creation can not be reverted in such a way, only database data. Assets will be created, but references to these assets will not be saved in database. Next time you run import, asset duplicates will be created, keep this in mind.

Microsoft Excel vs LibreOffice

If you use Microsoft Excel you need to turn off image compression (it's a file-level setting), otherwise the images will be scaled down.

LibreOffice does not seem to compress the images by default, and also it has a very convenient menu option to scale and resize image representation to fit the cell size (right click on image->fit to cell), while preserving original image resolution. Also, the image anchor is shown when the image is selected.

Releases