Minecraft Wiki:Style guide/Redstone

This style guide exists to establish a single convention for write-ups of redstone circuits and mechanisms.

Description
Each redstone structure should be described by some combination of text, schematic(s), and screenshot(s).


 * Structure Name
 * Structure names should be descriptive and unique, but it is not necessary to create unique names for structures which are topologically similar (they perform the same action with the same components but vary in the exact position of the blocks).


 * Screenshots and Schematics
 * Use thumbs for all screenshots and old-style (.PNG) schematics.


 * Arrangement
 * In general, the "primary" description should go to the left or top. (For English; in languages that are read right-to-left, make that "right or top".)
 * Thumbnails (screenshots and old schematics) should either go to the right in a column, or below in a gallery.
 * If a schematic is small and has a lot of text associated with it, it can also go to the right.
 * For large schematics and groups of related schematics, a long text passage can go on the left if there's room (otherwise force it to below the schematic), but if it's just brief descriptions, let those flow to the right or force them to below the schematic.
 * You can use the template to force everything following it to be below everything before it.  Make sure to use this at the end of a section/before a header.

Text
Describe any important features of the structure. Some topics to address might include:


 * Usage
 * Describe the purpose of the structure. Explain why it's used or what function it serves as part of a larger structure.
 * When writing up a number of structures which all provide the same function, consider writing the usage section only once to cover all of them. For example, if you are writing up a number of AND Gates, you could use a single usage section to discuss the purpose of AND Gates and then move on to describing the different ways to build an AND Gate without having to duplicate a discussion of their usage with each structure description.
 * Usage is the only part of the description that should be considered required for every redstone structure (or for a set of structures which provide the same function).


 * Features
 * List significant features of the structure. Possible features include: 1-wide, 1-high, flat, flush, silent, etc. Other important features include a structure's tileable size (the minimum dimensions in which it can be tiled), the delay it incurs as a sub-circuit, etc.
 * When describing a structure's size, list it as H1&times;H2&times;V (i.e., the two horizontal dimensions, then the vertical dimension), with the shortest horizontal dimension first (for example, 1&times;5&times;3 for a structure 1 block wide, 5 blocks long, and 3 blocks high). Always include any required blocks in the structure's dimensions, including blocks necessary to support redstone components.  (That is, "in-a-void" dimensions.)  Note that most "flat" circuits will be counted as two blocks high, except for the very few which need no supporting blocks.  Use   to create the multiplication symbol, , or just use a letter x.


 * Terminology
 * Explain any new terminology used when naming or discussing a structure. If explaining the terminology would be complicated enough to overwhelm the discussion of the structure itself, consider linking to an explanation of the terminology provided somewhere else.
 * Like usage, this part of the description may be needed only once for a set of structures which provide the same function.
 * Examples:
 * Edge Detector Circuits are named for the length of the pulse they generate and for whether they detect the rising or falling edge of a pulse (or both). For example, a "1-tick Rising Edge Detector" would generate a 1-tick pulse output whenever the its input changes from OFF to ON. To further differentiate edge detectors of the same type, add more descriptive terms to the beginning of the name -- for example, "Repeater-Piston 1-tick Rising Edge Detector".
 * The T Flip-Flop is a bistable circuit (its output doesn't change until it receives new input).
 * If no new terminology is used, omit this topic.


 * Construction
 * Explain any construction details not obvious from screenshots or schematics.
 * Also explain whether there are issues that may arise due to the order in which you build a structure. Some structures will not work correctly unless certain blocks are placed in the correct order, others may (undesirably) start operating like a clock if some blocks are placed before others, etc.
 * If there are no important issues with the structure's construction, omit this topic.


 * Behavior
 * Some structures may benefit from an explanation of how they work. For example:
 * Structures which depend on the quasiconnectivity feature.
 * Structures which depend on the timing of their elements working together.
 * If behavior is obvious, omit this topic.


 * Considerations
 * Discuss any important issues with the structure. Possible considerations include:
 * Comparisons to other structures which provide the same function.
 * Material cost.
 * Compactness.
 * Behavior as a sub-structure.
 * Signal delay.
 * Pulse length modification.
 * Dependence on, or compromises due to, bugs or glitches which might be patched later.
 * Noise of: buttons, levers, pressure plates, tripwire hooks, pistons, doors, trapdoors, fence gates, dispensers, etc.
 * Possible interference with other structures.
 * If there are no important considerations, omit this topic.


 * Variations
 * Discuss significant topological variations (using the same components and mechanics, but arranged slightly differently). Minor variations don't need to be discussed if they don't offer some benfit over the original design. Use additional schematics to illustrate variations, if necessary.
 * If there are no significant variations, omit this topic.


 * Earliest Known Publication
 * List the date that the structure was first published. Cite original publication as reference.
 * If the earliest publication date is unknown, omit this topic.

Topics don't necessarily need to be titled in the structure's description -- a single paragraph might address multiple topics with a sentence each, or each topic might consist of multiple paragraphs for a complicated structure.

Schematics
The preferred method for creating schematics on the wiki is the schematic template.

It is permissible to upload screenshots of schematics from redstone simulator programs, but expect them to get converted by someone else later (or you can do it when you get the chance). Don't use animated GIFs to show multi-layer schematics -- the speed of animated GIFs cannot be modified by the viewer, and not everyone can read schematics as quickly as they appear and disappear.

Large or numerous schematics can overburden the server when trying to render the page:
 * Pages with templates will take longer to respond when saving or previewing, and if that takes too long, the process will fail with either a blank white screen, or a "Server at Capacity" error.
 * If the page load does fail, the browsers "Page Back" button will work better than a refresh to get back to your edit buffer.
 * The load time increases with the total number of sprites in all schematics on the page. Stacked sprites cost proportionately more server time than unstacked ones: if N sprites are stacked in a tile, the cost is about (2&times;N)-1. Thus dual-layer diagrams are much more "expensive" against the page limits.

There are two methods for handling too many schematics, both involving "offloading" schematics to subpages that can be loaded into the main page at the user's request:
 * Preferred: LoadBox creates a box into which a subpage can be loaded. It is intended for a small amount of content (a single schematic or a group of schematics). LoadBox takes two parameters: the subpage path, expressed as wiki link text (e.g., ), and a box title.
 * LoadPage creates an article section into which a subpage can be loaded. It is intended for large amounts of content which would normally be an entire section in an article, but which is offloaded because of performance issues. LoadPage takes three parameters: the filename, the title that will show before loading, and the header level you want for that title.  Example:  if your current page is "Frammistat", and your diagram is the second Widget, you can insert the call: , and transfer the diagram to the page "Frammistat/Widget 2".

Use LoadBox rather than LoadPage when possible, because it keeps the majority of the article's content within the article, making it easier to read through the article and ensuring that search results lead to the article and not to a subpage with no obvious means of getting to the main article.

Captions
Add  to the caption of the first schematic in an article, and to additional schematics if that would be helpful. This will create a standard help link to Help:Schematic.

Content
Use the standard identifiers for different roles instead of your personal block preferences. These generate schematics that match the conventions used for screenshots. For redstone circuits, the important distinctions among blocks are solidity, and opacity vs. transparency.
 * Use  and   to indicate where a circuit begins and ends. Currently, these default to showing lime and pink wool respectively:  and . If you have more than one kind of input or output (say, clock or control lines as well as data), mark them with overlaid letters (e.g., ), and identify their role in the text.
 * Use  (mnemonic: "Stationary Block") to indicate a solid opaque block required for redstone purposes (supporting redstone components, transmitting power, etc.). Currently, this appears as.
 * Use  (mnemonic: "Moving Block") to indicate a solid opaque block that will be moved by pistons. Currently, this appears as .  Don't use this if it matters what sort of block is being moved, as with sand or a block of redstone; then you should use the specific block type instead.
 * Use  and   (mnemonic: "top slab") to indicate a transparent block that can support redstone dust (e.g., glowstone, upside-down slabs, etc.).  Currently, these appear as, and  (top and side views). That is, when you have a choice between glowstone, upside-down stairs, and a top slab, use the top slab. If you could also use glass (the block does not need to carry redstone) then you can show it as   or as glass.
 * Use  (mnemonic: "Any Block") to indicate a solid block that is needed for structural purposes, but not for redstone purposes (containing water or lava, blocking mobs, placing ladders, fending stray updates off of a BUD, etc.). Use this if the block could be any building block, such as dirt, obsidian, or glass. Currently, this appears as.

Temporary blocks (meant to be placed, then removed while building) can be shown as any easily-removed block that's not otherwise used in the diagram, and would not behave oddly. Some options are dirt or leaves. It's not necessary to show blocks that would only be used for placing other blocks (such as putting a block in midair).

Anywhere a particular block is needed, use that block. Examples include dirt or farmland for farming, obsidian for durability, and so on. If you have options, use the least expensive or least exotic block that would do (e.g. Jack-o-lanterns rather than glowstone).

Any use of darkening should be explained in caption or text. For MCRS diagrams, darkening meant "solid block above"; since that has been replaced by the transparent sprites (see below), a darkened block is now ambiguous. However, it can still be used to indicate occasional stacking, or other situations that would otherwise require a separate level diagram.

Lightening is used to indicate a significant block that would not normally be shown on this level, and is not covered or underlaid by this level. Usually, that means the input and/or output blocks, but you can use it sparingly to avoid an extra level diagram that would just be one or two items.

Repeating sections of an expandable circuit can be indicated with ellipsis sprites.

Layout
Multi-layer schematics can be done two ways. Use whichever seems more understandable, but don't mix them for a single structure.


 * Multiple single-level schematics
 * Single-level schematics, each showing all blocks, dust, and components at the same Y coordinate, with no stacking. Each level of the structure gets its own schematic. A variation of this is the sideview schematic for 1-wide structures. This is recommended for non-redstone schematics, as it is less burdensome on the server and few blocks have transparent versions.


 * One or more dual-level schematics
 * Dual-level schematics show two levels at a time: blocks, components, or empty space, but all in a two-block layer. For three- or more-layer circuits, do a separate schematic for each pair of adjacent levels: 1/2, 2/3, and so on. These might make circuits clearer, but be aware that stacked sprites count extra against the page limits.
 * Use the transparent sprites (, ,  , and  ) for blocks that are "covering" another block. One solid block atop another can be shown by darkening the block. If you are stacking blocks of different colors (say, a mobile block atop a stationary one), note it in caption or text, as this will otherwise be unclear.
 * If there are only one or two items on a third level, you might be able to use darkening or lightening to avoid an extra layer diagram, but make sure the result is understandable (then note it in caption or text anyway). Otherwise, don't try to cram in a third level.
 * Not every circuit is suited for dual layers, and especially mechanisms don't do well; if it looks confusing or you are having trouble showing what's going on, switch back to single-layer diagrams.

Screenshots
Along with redstone schematics and written explanations, screenshots illustrate the correct way to construct redstone structures. When creating screenshots, structures should be built and shot in a consistent way so that users can quickly learn to identify which blocks in an image are part of the structure and what they do, and which blocks are there to help explain it, etc.

A screenshot can contain multiple structures if that would help to illustrate differences between different structures, or to illustrate variations of the same structure.

Building the structure

 * Background
 * Structures should be built and shot in front of a plain, non-distracting background.
 * The preferred background is a sandstone superflat world (like the Redstone Ready superflat preset), with no other blocks or mobs in the picture. Other possible backgrounds might include: the void, the sky (for under-shots, with clouds turned off), or other superflat worlds made from grass block, iron blocks, glass, etc.


 * Positioning
 * Build structures off the ground (free-floating in the air) so that they can be shot from any direction and so that it's clear exactly which blocks are part of the structure.


 * Blocks
 * Use the following blocks to build the structure and then remove all unnecessary blocks:
 * Redstone components: Use redstone torches, wire, and repeaters, as needed.
 * Opaque blocks: Use a gold block for all opaque blocks that are necessary to the structure (to support redstone torches, wire, and repeaters or to provide power to another element of the structure, etc.). For complicated redstone structures, consider using different colors of wool (instead of gold blocks) to distinguish different functional parts of the structure.
 * Moving blocks: Use a diamond block for all blocks intended to be moved by a sticky piston. This helps to illustrate the moving parts of a piston-based structure in a static screenshot.
 * Upside-down slabs: Use a stone slab for upside-down slabs required by the structure.
 * Only use upside-down slabs when they are necessary to the structure (because they can act as diodes, to avoid cutting redstone below, to avoid powering a block in that location, etc.).
 * Where an upside-down slab, upside-down stair or glowstone can be used interchangeably in a structure, use a stone slab.
 * Structural blocks: Use a stone bricks block for all blocks required for structural purposes, but not for redstone purposes (retaining water of lava, confining mobs, etc.). Use glass instead when that would help clarify internal structure.
 * Other blocks: Use any additional blocks required by the structure (such as pistons) or necessary to illustrate the purpose of the structure (for example, a structure intended to control a door should include the door in the screenshot).


 * Input/Output Lines
 * When it would be helpful to understand the structure, include additional blocks outside of the structure to illustrate how signals enter and exit the structure.
 * Inputs should use lime wool as a background. For structures controlled by buttons, levers, etc., use lime wool to support the power component. For structures which receive input from another sub-structure, use lime wool as the supporting block for redstone wire, redstone repeaters, etc.
 * Outputs should use pink wool as a background.
 * Duplex I/O (where the same point can be both an input and an output), can be indicated with light blue wool.
 * Buses (wire lines between structures) should be laid on white wool. Other colors may be used for multiple buses if that would improve clarity.

Taking a screenshot

 * Preparation
 * Before taking a screenshot, take the following steps:
 * Remove or deactivate mods that would affect the screenshot (unless they're specifically about a mod, all Minecraft Wiki screenshots should represent Minecraft "out-of-the-box"). Mods that wouldn't affect the screenshot, or would get cropped out later, are fine.
 * Set Texture Pack to Default (see above).
 * Set Graphics to Fancy.
 * Set FOV to Normal (the lowest setting, to minimize perspective distortions).
 * Set Particles to Minimal (to remove particles from redstone torches which might obscure or be mistaken for redstone wire).
 * Set Smooth Lighting to ON (to subdue distracting block shadows).
 * Set Clouds to OFF (only if you're intending to use the sky as a backdrop).
 * Set view to first-person (you shouldn't be in the shot). Use F5 to switch to first-person.
 * Turn off the GUI by pressing F1.


 * Taking the Shot
 * Angle: Make sure the entire structure is in the picture, including input/output lines and other illustrative blocks if present. Make sure there is additional space around the structure in your framing so that it has a nice border and you have room to do some cropping later. Try to find an angle that illustrates all important elements of the structure, but some structures may require multiple angles/shots to illustrate everything.
 * Stand on a block rather than flying over the structure. Flying expands your "field-of-view" (FOV) which increases perspective distortion, so standing is better for taking pictures. The block can be in any position that gives you a good shot, and if you need to take the picture again the block will make it easier to get back in position.
 * Make sure no mobs have wandered into frame, and that there are no other stray entities (such as dropped items) that would clutter the shot.
 * Lighting: Take screenshots in the daytime, unless necessary to illustrate a feature of the structure (if you have command privileges, use /time set 6000 to set the time to noon right before the shot).
 * Press F2 to take the screenshot (or use your own screen capture software).

Finishing up

 * Editing
 * Screenshots may need clean-up to improve clarity, but this may require some knowledge of image editing software. If you don't know how to do this, or can't, go ahead and upload your image -- hopefully someone will fix your image later (yay, wikis!).
 * Cropping: Crop the image so that the structure takes up most of the picture, but leave some border so the structure isn't crowding the edge.
 * Color Adjustment: Some screenshots may need their color adjusted to improve clarity (especially screenshots of oscilloscopes while the game is paused and dimmed).
 * File Type: All uploaded screenshots should be of type .png (Portable Network Graphic). F2 screenshots are PNGs by default, but if you use other screen capture software you may need to convert the image to a PNG with image editing software.


 * Upload the image to the Minecraft Wiki.
 * Start at the Upload File page.
 * Use the Browse button to find the image on your computer.
 * Add a description!
 * Set the Licensing menu to "This file is a screenshot of/uses textures from Minecraft".
 * Check everything and then hit the Upload File button.


 * Add the screenshot to an article.
 * Images that aren't used by articles may get deleted after a while.
 * To add a default thumb like the example screenshot above, use.
 * is the name of the file (e.g., ).
 * is the text to appear under the image.