Table of Contents

Editor: CSV Table Writing

CSV Tables

A comma-separated file (CSV) is a common format for storing data in a file. This is the standard file type used in Excel and is common to read. The Unreal Engine natively does not have Blueprint functions to read and write to CSV files. However, Nominal has provided helper functions to work with CSV files. This particular document will demonstrate how to write a CSV file with particular data. A CSV file object can be created in a level blueprint by first using the Construct Object from Class node. The class to use is CSVTable and the Outer should be set to the level blueprint.

Untitled

Note

There is a class called CSVFile that already exists. This is a deprecated class and does not have all the functions required. Make sure to use CSVTable when dealing with reading and writing these files.

Creating a File

Once the object has been constructed, the CSV file can be created using the Create function. This takes in three parameters:

  • File: This is the full file path to the CSV file location. The file should end with .csv, but if it doesn’t the system will add the extension for you.
  • Column Names: This is the string array of headers that the file should contain. At this point, the headers should be known but additional headers can be added later.
  • Separator: Although a comma is the most common separator between cell data, other separators can be used. For example, if storing JSON data, a better separator would be the pipe (’|’).

To create a file path, use one of Unreal’s standard pathing directories which will provide the full path to a particular location within the project. This includes Project Dir, Project Content Dir and Project Saved Directory. In this case, a file will be saved to a new folder inside the Saved directory of the project.

Untitled

Note

The folder must exist when specifying the file path. New folders may not be created if they are included in the path. Additionally, when a file is created, it will not be saved. Files are only saved when the Save function is called on the csv table.

Adding Data

New rows can be added to the CSV table using the Add Row function. This takes in an array of data that corresponds to the row. This data must be in the same order as the headers defined in the Create function. By default, if no data is passed in, a new empty row will be created and added to the CSV table. This function will add a new row to the bottom of the table.

Untitled

The Insert Row function can add a row to a particular location in the table. For example, the index of 0 would add the row to the very top of the table, before the first entry has been added.

Setting Cell Data

Both strings and doubles can be written to the CSV file. These are done using the Set Cell functions. For each data type, there is an index and a name option. The index option allows a particular column index (based on the headers where 0 corresponds to the first header). The name option allows a specified name of the header to set the cell data. If the header or index does not exist, the data will not be added.

Untitled

Deleting Data

Data can be deleted using the Delete functions on the CSV table. Several functions can be used here:

  • Delete All: This function will delete all data from the table. This will not delete the headers, but rather all data within the actual rows.
  • Delete Column (Index): Removes a particular column from the CSV table. This is designated by the index starting at 0.
  • Delete Column (Name): Removes a particular column from the CSV table. This is designated by the name of the column that was defined in the headers.
  • Delete Row: Removes a particular row from the table based on the index. This starts at 0 at the top of the table and ends at the bottom. To delete the last row on the table, use -1. Any negative number will attempt to delete a row from the end of the table upwards.
  • Delete Rows: Removes multiple rows from the table, starting at one index and ending with the number of rows specified in the count parameter.

Sorting Data

Data within the CSV table can be sorted. This can be sorted both by name (if sorting by a string column) or by number (if sorting by a numeric column). This permanently changes the order of data in the table which, when saved, will export the data in a different way than how it was pre-sort. The Ascending flag will determine whether the data should be sorted in an increasing or decreasing order.

Untitled

Adding Columns

The Add Column (Name) adds a new column by name to the CSV table. The column name must be unique to the other column names added. An additional parameter is defined named the Default. This is the value that will be initialized to all rows that currently exist. If the default value is numeric, a number will be added to all rows.

Saving Data

It is important to save the data as the table is not written to the CSV file until the Save function is called. All data loaded within the object is then exported as a .csv file to the designated location specified when it was created. Additionally, there is a Save As function which will make a copy of the current file and save it to a new location. This can be useful for adding new data without affecting the previously saved file.

Untitled

Warning

Any data that is not saved when writing data to the CSV file will not be updated in the output .csv file. Make sure to save changes at each point or the end of the level. Typically, this is done on the Event End Play function on the level blueprint.